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Preface 


Intended Audience 

This manual is intended for use by programmers familiar with the VAX RPGII language. 
It is designed to be used both as a reference manual and as a user's guide. 

Document Structure 

This manual contains 12 chapters in Part I (programming information), 3 chapters in Part 
II (language information), and 3 appendixes. 

Parti 

Chapter 1 Explains the VAX RPG II logic cycle. 

Chapter 2 Explains how to compile, link, and run programs. 

Chapter 3 Explains how to use the VAX RPG II editor to create and edit programs. 

Chapter 4 Explains how to use VAX RPG II indicators. 

Chapter 5 Explains how to manage files. 

Chapter 6 Explains those elements that affect printer output files. 

Chapter 7 Explains how to create and access tables. 

Chapter 8 Explains how to create and access arrays. 

Chapter 9 Explains how to use the VAX RPG II CALL interface to access RTL pro¬ 
cedures, system services, and subprograms. 

Chapter 10 Explains how to use the VAX Symbolic Debugger to debug VAX RPG II 
programs. 
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Chapter 11 Explains the format of a listing file. 

Chapter 12 Explains how to improve the efficiency of programs. 

Part II 

Chapter 1 Explains VAX RPGII elements and data types. 

Chapter 2 Lists specifications, allowable entries, and their functions. 

Chapter 3 Explains how to use VAX RPG II operation codes. 

Appendix A Lists the VAX RPG II character sets. 

Appendix B Explains the differences between the PDP-11 RPG II and the 
VAX RPG II language and editor. 

Appendix C Shows PCA applied to an RPG II program. 

Conventions Used In This Document 

Conventions Meaning 

| The RPG II editor cursor is represented by a box. 

[ ] Brackets enclose an optional portion of a format. 

{ } Braces enclose a mandatory portion of a format. 

A vertical ellipsis indicates that not all of the program lines in an 
example are shown. 

Definitions 

In this manual, the following definitions apply: 

Column name The first letter of the first word of a column name is capitalized. For 

example, Alternate collating sequence. 

Program module A program module is a VAX RPG II main program or a subprogram. 

Subprogram A subprogram is a separately compiled program module that must be 

linked with the main program. 

Subroutine A subroutine is a block of code executed by the EXSR operation code. 
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Important Information 


The on-line release notes contain some brief information on the product, last-minute infor¬ 
mation that was discovered too late to be printed in the documentation, and any known 
restrictions. After you install VAX RPGII, read the release notes interactively by typing 
the HELP RPG RELEASE_NOTES command. You can print the release notes by typing 
the following DCL commands: 

$ HELP/OUTPUT=RPG*LIS RPG RELEASE_N0TES 
$ PRINT/DELETE RPG*LIS 

Following is a list of some common problems and how to work around them: 

• Leave the editor and make sure that the VMS terminal characteristics are set prop¬ 
erly for your terminal by typing the SET TERMINAL/INQUIRE command if the fol¬ 
lowing error message is displayed: 

7.TPU-E-N0NANSICRT t SYS$INPUT must be an ANSI CRT 

If you are using a VKIOO(GIGI) terminal and the terminal screen does not appear to 
update correctly, leave the editor and type the SHOW TERMINAL command to make 
sure that the device is a VK100. If it is not, type the SET TERMINAL/INQUIRE com¬ 
mand to make sure that the VMS terminal characteristics are set properly for your 
terminal. 

• Use the RPG/CHECK:BLANKS_IN_NUMERICS command to convert blanks in 
numeric data to zeros if you run your program and receive the following message: 

A numeric field contains invalid data 

• If the line printer listing of a printer output file is not spacing as you expect, make 
sure you are using the /NOFEED qualifier with the PRINT command. 

• If a source line in the compiler listing contains one or more periods (.) where you have 
not entered a period in the program line, it is because the program line contains a 
nonprintable character (for example, a TAB character or a null character). It is possi¬ 
ble to enter nonprintable characters when using an editor other than the RPG II edi¬ 
tor to create or edit a program. 

• Make sure you have a BYTLM quota of at least 8192, a PRCLM quota of at least 1, and 
the TMPMBX privilege if you receive the following message immediately after invok¬ 
ing the RPG II editor COMPILE command: 

Subprocess not activated - 

leave editor and check quotas and privileges 
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• If you continue to get the above message when using the RPGII COMPILE command, 
increase the BYTLM quota. 

• Make sure you can run the compiler without problems using the RPG command at the 
DCL command level if you receive the following message: 

Unexpected error during compilation - 
leaue editor and try DCL RPG command 

If you have no problem running the compiler using the RPG command, increase the 
BYTLM quota. 

The BYTLM and PRCLM quotas and the TMPMBX privilege can be changed by the 
system manager using the VAX/VMS AUTHORIZE utility. 



Chapter 1 

The VAX RPGII Logic Cycle 


VAX RPG II is an extended implementation of the RPG II language that was developed by 
IBM as a problem-oriented language for commercial applications and includes DIGITAL 
extensions for integration with the VMS architecture. In general, VAX RPG II is a lan¬ 
guage processor that provides a convenient means of preparing a wide variety of reports 
and other commercial data processing applications. VAX RPG II runs under the VAX/VMS 
or Micro VMS operating system and consists of a compiler and editor. 

RPG II is a nonprocedural language; every program compiled by the RPG II compiler exe¬ 
cutes according to a fixed, predefined logic cycle. Unlike the logic of a procedural language 
such as COBOL, the logic is not supplied by the programmer, but is built into the compiler. 
This built-in logic is called the RPG II logic cycle. The execution of an RPG II program 
consists of a number of iterations of the logic cycle. 

The RPG II specifications you code determine what happens within the various phases of 
the logic cycle, but cannot change the basic sequence of program execution. 

For example, you can code an Input specification to program RPG II to recognize and pro¬ 
cess a particular record type, but you cannot program RPG II to read three input records in 
a row, print a report heading, load a table, immediately write four different output records, 
and then perform some total calculations; this series of steps, while perfectly acceptable in 
a COBOL program, does not fit into the predetermined structure of the RPG II logic cycle. 

The fixed logic cycle of RPG II was designed specifically to accommodate the sequence of 
operations needed to generate most common business reports and file maintenance func¬ 
tions. However, the fixed nature of the RPG II logic cycle does not prevent you from control¬ 
ling the set of functions performed for each input record, and, to some extent, the sequence 
and timing of these functions. For example, by setting various indicators (see Part I, Chap¬ 
ter 4) on or off when certain conditions occur, you can actually affect the sequence of pro¬ 
gram execution within the phases of the general logic cycle. Therefore, to write effective 
RPG II specifications, and to take advantage of what flexibility and control RPG II does 
provide, you must thoroughly understand the structure and timing characteristics of the 
overall RPG II logic cycle, and recognize both RPG IPs special capabilities and its 
limitations. 
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1.1 The RPGII General Logic Cycle 

Every RPG II program follows the same basic series of execution steps, which form the 
general logic cycle. Some of the programs you write will need to call upon one or more of the 
additional operations of RPG II: matching fields, chaining, overflow processing, and look¬ 
ahead processing. Each of these additional operations is executed according to a fixed logic 
cycle within the overall logic cycle of the program. These functions are described later in 
this chapter. 

The RPG II general logic cycle is executed once for each input record of a primary or secon¬ 
dary file. The general logic cycle consists of the following three steps, performed in order 
for each record: 

1. Inputting a record 

2. Performing calculations 

3. Outputting one or more records 

Each logic cycle begins when a new record is input, and ends just before the next record is 
input. The RPG II specifications you code determine the range and type of specific func¬ 
tions performed during each phase. During the calculation and output steps within each 
cycle, there are two distinct timing phases: 

• Total time — operations are performed on summary data accumulated from a group of 
related records. 

• Detail time — operations are performed on individual records. 

Sections 1.4.1 and 1.4.2 describe total-time and detail-time characteristics and operations. 

The first and last iterations of the RPG II logic cycle are somewhat different from all other 
iterations. Sections 1.2 and 1.3 describe these differences and explain how you can take 
advantage of them. 

1.2 The First Cycle 

When program execution begins, and before the first input record is read, several one- 
time-only operations are performed. You can exert control over this process by providing 
detail-time output records Conditioned by the IP (first-page) indicator, and by using output 
specifications with either no conditioning indicators or with all negative conditioning 
indicators. (See Part I, Chapter 4 for more details on conditioning indicators.) During the 
first cycle, RPG II performs the following initialization operations: 

• Obtains the current date (UDATE, UDAY, UMONTH, and UYEAR - see Part I, 
Chapter 6). 

• Opens all files (see Part I, Chapter 5). 
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• Loads pre-execution-time tables and arrays (see Part I, Chapters 7 and 8). 

• Initializes page number counters. 

• Prints heading and detail lines conditioned by the IP indicator, by all negative indica¬ 
tors other than the IP indicator, and by no indicators. 

Although all iterations of the logic cycle (other than the first) include a total-time phase, 
RPG II bypasses all total-time calculations and total-time steps during the first cycle 
unless the LR (last-record) indicator is on. This behavior, like the logic cycle itself, is built 
into RPG II. 

After initialization tasks are performed, RPG II reads the first record in the primary file, if 
used, and then reads the first record in each secondary file, if used, and determines the type 
of each record read. 

1.3 The Last Cycle 

The last cycle is performed after all the records you specified for processing until end-of-file 
have been read from all primary and secondary files. When the last record from the last file 
has been read, RPG II sets on the LR (last-record) indicator and all the control-level indica¬ 
tors (LI through L9). Then, after this last record has been processed, RPG II performs the 
following operations: 

1. Performs total-time calculations. 

2. Writes total-time output. 

3. Outputs any tables or arrays that have output files associated with them. 

4. Closes all files. 

5. Ends program execution. 

1.4 A Normal Cycle 

A normal cycle in an RPG II program can be defined as any cycle but the first or the last. 
During a normal cycle, RPG II performs all operations necessary to process a single input 
record. Because of the nature of most RPG II applications, a normal program cycle includes 
two special phases — total time and detail time. Total time occurs before detail time. A 
normal cycle consists of the following sequence of steps: 

1. Outputting heading lines, if specified 

2. Outputting detail-time information pertaining to the previous record 

3. Reading an input record 
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4. Performing total-time calculations for the previous record, if required 

5. Performing total-time output 

6. Checking the LR (last-record) indicator; if it is on, terminates the program (see 
Section 1.3 above) 

7. Processing the record read in Step 3; performs all detail-time calculations 

Steps 4 and 5 constitute total time; Steps 1, 2, and 7 constitute detail time. 

This list of steps in a normal cycle is an overview only. See Figure 1-1 for a complete 
description of a normal RPGII logic cycle. 


1.4.1 Total Time 

During total time, RPG II checks which control-level indicators (LI through L9) you have 
defined, and the control field you have associated with each. For example, if your applica¬ 
tion involves the generation of a monthly sales report, you may have associated indicator 
L9 with the grand total of monthly sales, indicator L8 with total sales by region, indicator 
L7 with total sales by district office, and indicator L6 with total sales by salesperson. (See 
Part I, Chapter 4 for details on using control-level indicators.) 
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If, during a particular cycle, it is determined that the salesperson identification number in 
the record just read is different from the salesperson number in the previous record, a con¬ 
trol break has occurred at the salesperson total level. At this point, your program will out¬ 
put the accumulated total sales for the salesperson whose number was found in the 
previous record. 

You might print each person’s name and sales total on a separate line. Or, you might choose 
to print a page heading (with a date), and then print a salesperson’s total sales, thus pro¬ 
viding a separate one-page report for each salesperson. The Output and Calculation speci¬ 
fications you code determine the contents, order, and appearance of your report. 

During another cycle, it might be determined that the region identifier of the record just 
read is different from the region number in the previous record. Given the control-level 
indicators described in the first paragraph in this section, this means that a three-level 
control break has occurred. In this situation, you must first output the accumulated total 
for an individual salesperson, then the accumulated total for a district office, and, finally, 
the accumulated total for the region. 

Similarly, after the last input record in the file has been read, a four-level control break has 
automatically occurred. At that point, your program must first output the accumulated 
total for the last individual salesperson in the last district office; then, the accumulated 
total for the last district office; then, the accumulated total for the last region; and, finally, 
the accumulated grand total of all sales for the month. 

After all control breaks have been taken care of, total time ends and detail time begins. 
Detail-time operations deal with the record just read. 

1.4.2 Detail Time 

During detail time, your program performs operations specific to each individual record. 
In the example described in Section 1.4.1, each time a record is read, the detail-time opera¬ 
tions might consist of the following steps: 

1. Printing an output line on your report. For example, each record in your file might 
contain a weekly sales figure for a particular salesperson. The report would list the 
week’s beginning and ending dates, and the sales figure. 

2. Adding the sales figure to all active accumulators. Then, when the next control 
break occurs, each accumulator will contain the correct amount. 

3. Performing any other operations you defined in your specifications. These might 
include moving data fields and handling errors. 

Figure 1-1 provides a detailed annotated illustration of a complete, normal RPG II pro¬ 
gram cycle. Each processing and decision box is numbered; the numbers are keyed to the 
annotations that immediately follow the figure. 
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1. First cycle 



Figure 1—1: RPG II Logic Cycle 
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Key to Figure 1-1 

1. This step is executed only during the first cycle. It initializes your program for exe¬ 
cution. Initialization consists of retrieving the date (if you specified UDATE, 
UDAY, UMONTH, or UYEAR), opening all files, and loading all pre-execution- 
time tables and arrays. 

2. RPGII writes heading and detail lines (identified by H or D in column 15 (Type) of 
the Output specification). Heading and detail lines are always executed at the 
same time. If conditioning indicators are specified, the conditions for the indicator 
must be satisfied. If the fetch overflow logic is specified, and the overflow indicator 
is on, RPG II writes the appropriate overflow lines. If the IP indicator is on (during 
the first cycle only), RPG II prints all lines conditioned by it, then sets the IP indi¬ 
cator off. RPG II executes this step at the beginning of the program so that heading 
lines can be printed before actual processing begins. 

3. RPG II checks whether any halt indicators (HI through H9) are on; if any are, the 
program terminates. If you do not want your program to terminate here, you must 
set all halt indicators off previous to this step. You can set halt indicators on, how¬ 
ever, at any time during the program. 

4. RPG II sets control-level indicators (LI through L9) and all indicators used as 
record-identifying indicators off. RPG II also sets overflow indicators (OA through 
OG, OV) off, unless they were set on during detail time (detail-time calculation or 
output operations) in the preceding cycle. All other types of indicators that are on 
remain on. 

5. Here, RPG II determines whether the LR indicator is on. If it is, RPG II branches to 
step 15 and sets on control-level indicators LI through L9, if used. 
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Key to Figure 1—1: RPGII Logic Cycle (Cont.) 

6. RPG II determines whether a primary file was specified by the program. If not, 
RPG II proceeds directly to step 16. 

7. If required, RPG II reads an input record from the last primary or secondary file 
processed. If this was an input file with look-ahead fields, the record is already 
available; therefore, no read operation may be necessary at this time. On the first 
cycle, a record is read from each primary and secondary file. 

8. RPG II tests the file just read for end-of-file. If end-of-file has been encountered, the 
program bypasses step 9. 

9. If RPG II reads a record from a file, the record type is determined and the record 
sequence is checked. If the record type cannot be determined, or the record is out of 
sequence, the program terminates. 

10. In this step, RPG II determines which file to process. If a FORCE operation was 
executed during the previous cycle, the forced file is selected for processing. (All 
records processed with a FORCE operation are processed with the MR (matching- 
records) indicator set off.) However, if the forced file is at EOF (end-of-file), the nor¬ 
mal multi-file logic selects the next record for processing. If no forced file was speci¬ 
fied, RPG II determines whether matching fields were specified. If so, the 
matching-fields routine is given control (see Figure 1-2). Otherwise, all records in 
a primary file are processed first, then the records from each secondary file in order 
of their specification. 
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Figure 1—1: RPG 
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Key to Figure 1-1: RPGII Logic Cycle (Cont.) 

11. Here, RPG II determines whether the LR indicator should be set on. The LR indi¬ 
cator is set on when the program has reached the end of all the files that you have 
specified for processing until the end-of-file, and when all the records from secon¬ 
dary files that match the last primary record have been processed. If the LR indica¬ 
tor should be set on, RPG II branches to step 15 and sets on indicators LI through 
L9. 

12. RPG II sets on the record-identifying indicator for the record selected for process¬ 
ing. 

13. RPG II determines whether the record selected for processing has caused a control 
break to occur. A control break occurs when the value in the control field of the 
record being processed differs from the previous value of the control field. See Sec¬ 
tion 1.4.1. for more information. 

14. If a control break has occurred, RPG II saves the contents of all appropriate control 
fields. 

15. If a control break has occurred, RPG II sets the appropriate control-level indicator 
(LI through L9) on; at the same time, RPG II sets all lower-level control-level 
indicators on. The LI through L9 indicators can be used for conditioning only if 
they have been defined as conditioning indicators. 
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Key to Figure 1-1: RPGII Logic Cycle (Cont.) 

16. RPG II determines whether total-time calculation and output operations should be 
performed. If control-level indicators are not specified in columns 59 and 60 (Con¬ 
trol level) of the Input specification, RPG II bypasses total-time calculation and 
output operations during the first cycle only; after the first cycle, RPG II performs 
total-time calculation and output operations for every cycle. 

If control-level indicators are specified, RPG II bypasses total-time calculation and 
output operations until after the first record with control fields is processed. When 
the LR indicator is on, RPG II always performs total-time calculation and output 
operations. 

17. In this step, RPG II performs all total-time calculations conditioned by a control- 
level indicator or containing L0 in columns 7 and 8 of the Calculation specification. 
Total-time calculations can include CHAIN operations, in which a record is imme¬ 
diately retrieved from an input file (see Figure 1-3), or READ operations, in which 
the next record is retrieved from a demand file. 

18. Here, RPG II writes all total-time output lines that satisfy the conditions specified 
by the indicators. If an overflow indicator (OA through OG, or OV) is on, and Fetch 
overflow is specified, RPG II writes the overflow lines as well. 

19. RPG II determines whether the LR indicator is on. If it is, RPG II performs table 
and array output, closes all files, and terminates the program. 

20. RPG II checks to determine whether any overflow indicators (OA through OG, and 
OV) are on. 
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Key to Figure 1-1: RPGII Logic Cycle (Cont.) 

21. If any overflow indicators are on, the overflow routine is given control (see Figure 
1-4). RPG II outputs all lines conditioned by those overflow indicators that are on. 
However, RPG II outputs these lines only if they were not output by Fetch overflow 
logic (step 2 or step 18). 

22. RPG II determines whether the MR (matching-record) indicator should be set on. 
If this is a multifile program, and the record being processed is a matching record, 
RPG II sets the MR indicator on; it remains on for the duration of the cycle during 
which the matching record is processed. If not appropriate, RPG II sets the MR 
indicator off. 

23. RPG II extracts data fields from the record to be processed, and sets the field indica¬ 
tors on or off, as appropriate, for those fields. 

24. RPG II then determines whether look-ahead fields are specified in the last file 
processed and whether it is an input file. 

25. If the last file processed was an input file with look-ahead fields, RPG II passes 
control to the RPG II look-ahead routine (see Figure 1-5). In this routine, RPG II 
retrieves the look-ahead record and extracts the look-ahead fields. If look-ahead 
fields are not specified, RPG II continues with detail-time calculations (step 26). 

26. This is the detail-time calculations step. Here, RPG II performs all conditioned 
detail-time calculations and subroutines. The calculations may include CHAIN 
and READ operations (see Figure 1-3). Detail-time calculations complete the 
RPG II logic cycle. Then, the cycle branches to step 2 to begin again. 
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1.5 RPGII Detail Program Logic Cycle 

This section consists of annotated flowchart diagrams that illustrate in detail various rou¬ 
tines within the predefined RPG II logic cycle. The following figures are provided: 

• Figure 1-2 illustrates the RPG II matching-fields routine. 

• Figure 1-3 illustrates RPG II file processing for chained and demand files. 

• Figure 1-4 illustrates RPG II overflow processing. 

• Figure 1-5 illustrates RPG II look-ahead processing. 
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Figure 1-2: Logic Cycle for the Matching-Fields Routine 
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Key to Figure 1-2 

1. RPG II determines whether the program uses more than one primary and secon¬ 
dary file. If multifile processing is in effect, processing continues with step 2. Oth¬ 
erwise, the program branches to step 3. 

2. RPG II compares the matching fields to determine which file is to be processed. 
RPG II extracts the matching fields and checks their sequence. 

3. If the matching fields are not in sequence, a run-time error occurs and the program 
terminates. 

4. RPG II moves the matching fields into a temporary buffer. The next record is 
selected, based on the value of the matching fields. 

5. RPG II returns to the program. 
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Figure 1-3: Logic Cycle for Chained and Demand Files 


Key to Figure 1-3 

1. RPGII retrieves the next record in the file specified by the CHAIN or READ opera¬ 
tion code. If the record is not found on a CHAIN operation or an end-of-file occurs 
during a READ operation and a resulting indicator is not specified, a run-time 
error occurs. If the record is not found on a CHAIN operation or an end-of-file 
occurs during a READ operation and a resulting indicator has been specified, the 
indicator is set on and control returns to the program. 

2. RPG II sets on the record-identifying indicator associated with the chained or 
demand file for the record type read. 

3. Then, RPG II extracts the fields from the record just retrieved. Also, RPG II sets on 
any field indicators associated with the record. 

4. RPG II returns to the program. 
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Figure 1-4: Logic Cycle for Overflow Processing 


Key to Figure 1-4 

1. RPG II determines whether the overflow lines were written previously, using the 
fetch overflow routine. If so, the program branches to the specified return point; 
otherwise, it continues with step 2. 

2. RPG II evaluates all overflow lines and writes those lines that satisfy the condi¬ 
tions of the indicator(s). 

3. RPG II returns to the program. 
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Figure 1-5: Logic Cycle for Look-Ahead Processing 


Key to Figure 1-5 

1. RPGII reads the next record for the file being processed. If the end of the file has 
been reached, all look-ahead fields are filled with 9s and control is returned to the 
program. 

2. RPG II extracts the look-ahead fields from the record. 

3. RPG II returns to the program. 
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Chapter 2 

Developing Programs 


You can create a source program using the RPGII editor (See Part I, Chapter 3); then, you 
must compile, link and run the program with commands to the VAX/VMS operating sys¬ 
tem. If your RPG II program does not execute correctly, you must modify it and repeat 
these steps until it does. 

When you compile an RPG II program, the RPG II compiler creates an object module file. 
When you link your program, you use the VAX Linker. The linker reads the object module 
file and uses libraries to replace external references with the address of the executable 
code that defines it. Then the linker places that code in an executable image file. When you 
execute your program, the system executes that image. 

2.1 Compiling Programs 

To compile a source program, use the RPG command. Its format is: 

RPG[/qualifier(s)] file-spec-list[/qualifier(s)] 
where: 

/qualifier(s) Specifies special actions the compiler is to perform. See Sections 2.1.2.1 
through 2.1.2.8 for information on qualifiers. 

file-spec-list Specifies the source file(s) to be compiled. Normally, you would specify a sin¬ 
gle source file, but if you need to create a single object file from more than 
one source file, separate the file specifications with plus ( + ) signs. RPG II 
appends the files in the order you specify. If you separate source file specifi¬ 
cations with commas (,), RPG II compiles the programs separately and cre¬ 
ates a single object file for each source file. 

When you execute the RPG command, RPG II compiles the program and generates an 
object module with the specified file name and the default file type OBJ. The compiler can 
also generate other output files, depending on the qualifiers you supply. 
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When you compile a source file with the RPG command and specify only its file name, the 
compiler searches for a source file with the specified name that: 

• Is stored on the default device in the default directory 

• Has a file type of RPG 

If more than one file meets these conditions, the compiler chooses the one with the highest 
version number. 

For example, assume that your default device is DBAO:, your default directory is [SMITH], 
and you give this command: 

$ RPG FIRSTTRY 
$ 

The appearance of the second DCL command prompt ($) indicates that the compilation is 
finished. 

The compiler searches device DBAO: in directory [SMITH], seeking the highest version 
of FIRSTTRY.RPG. If you do not specify an output file, the compiler generates the file 
FIRSTTRY.OBJ and stores it on device DBAO: in directory [SMITH]; with a version num¬ 
ber that is one higher than any existing version number for FIRSTTRY.OBJ. 

2.1.1 Default Compiler Options 

When you compile a program, you can specify options like /LIST or /NOWARNINGS. The 
options you get when you do not specify them are called defaults. 

You can change these defaults for your own programs by using qualifiers with the RPG 
command. The RPG command accepts qualifiers to change the defaults for a single compi¬ 
lation, as shown in the following example: 

• RPG/LIST/NOOBJECT MYPROG 

This RPG command tells RPG II to compile a single source file (MYPROG.RPG), and over¬ 
rides the default compiler settings for 

• Listing — The RPG II compiler will produce a compiler listing. 

• Object file — The RPG II compiler will not produce an object file. 

You can specify other defaults by defining RPG as a symbol, as shown in the following 
example: 

$ RPG : = = "RPG/CHECK/LIST/CROSS" 

If you type RPG MYPROG, the /CHECK, /LIST, and /CROSS qualifiers are in effect. 
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2.1.2 RPGII Compiler Qualifiers 

This section describes the RPG command itself; Sections 2.1.2.1 through 2.1.2.8 describe 
the RPG command qualifiers and list their default values. 

You can change defaults by using qualifiers with the RPG command. Qualifiers have the 
form: 

/qualified = value] 

Many qualifiers have a corresponding form that negates the action specified by the quali¬ 
fier. The negative form is: 

/NOqualifier 

For example, /LIST tells the compiler to produce a listing file; /NOLIST suppresses the 
listing. 

You can specify qualifiers so that they affect either all files in the command, or only certain 
files. If the qualifier immediately follows the RPG command, it applies to all files, as shown 
in the following example: 

$ RPG/LIST ABC #XYZ>RST 

This command specifies listing files for ABC.RPG, XYZ.RPG, and RST.RPG. 

Qualifiers following a file specification (with some exceptions) affect only the associated 
file, as shown in the following example: 

$ RPG/LIST ABC»XYZ/NOLIST»RST 

The above RPG command specifies listing files for ABC.RPG and RST.RPG, but not for 
XYZ.RPG. Qualifiers to a single file specification in an appended list of file specifications 
are exceptions to this rule. (A list of file specifications separated by plus signs is called an 
appended list.) See Example 5 in the following list. 

1. $ RPG/LIST AAAtBBBtCCC 

RPG II compiles source files AAA.RPG, BBB.RPG, and CCC.RPG as separate files, 
produces three object files (AAA.OBJ, BBB.OBJ, and CCC.OBJ), and three listing 
files (AAA.LIS, BBB.LIS, and CCC.LIS). 

2. $ RPG XXX + YYY + ZZZ 

RPG II appends source files XXX.RPG, YYY.RPG, and ZZZ.RPG, and compiles 
them as a single program. This command produces one object file named 
XXX.OBJ, but does not produce a listing file. 

3. $ RPG/OBJECT=SQUARE CIRCLE 

RPG II compiles source file CIRCLE.RPG and produces object file SQUARE.OBJ. 
This command produces no listing file. 
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4. * RPG AAA + BBB ,CCC/LIST 

RPG II produces two object files: AAA.OBJ (created from AAA.RPG and 
BBB.RPGj, and CCC.OBJ (created from CCC.RPG). RPG II also produces the list¬ 
ing file CCC.LIS. 

5. $ RPG ABC+DEF/NOOBJECT+XYZ 

RPG II appends and compiles the source files ABC.RPG, DEF.RPG, and XYZ.RPG. 
Because qualifiers in a list of appended files affect all files in the list, this command 
suppresses the creation of an object file. 

Table 2-1 lists the qualifiers you can use with the RPG command. 


Table 2-1: RPG II Command Qualifiers 


Qualifier 

Negative Form 

Default 

/CHECK = [NOJBOUNDS 

[NO]RECURSION 

/NOCHECK 

/NOCHECK 

[NO]BLANKS_IN_NUMERICS 

ALL 

NONE 


/CROSS-REFERENCE 

/NOCROSS-REFERENCE 

/NOCROSS-REFERENCE 

/DEBUG = [NOJSYMBOLS 

[NOJTRACEBACK 

ALL 

/NODEBUG 

/DEBUG = (TRACEBACK,NOSYMBOLS) 

NONE 



/LIST[ = file-spec] 

/NOLIST 

/NOLIST (interactive) 

/LIST (batch) 

/MACHINE-CODE 

/NOMACHINE-CODE 

/NOMACHINE-CODE 

/OBJECT! = file-spec] 

/NOOBJECT 

/OBJECT 

/SEQUENCE-CHECK 

/NOSEQUENCE-CHECK 

/NOSEQUENCE-CHECK 

/WARNINGS = [NO]OTHER 

[NO]INFORMATION 

ALL 

NONE 

/NOWARNINGS 

/WARNINGS = (OTHER,NOINFORMATION) 


Sections 2.1.2.1 through 2.1.2.8 describe RPG II command qualifiers in detail. 

2.1.2.1 CHECK 

The CHECK qualifier causes RPG II to check for errors in array indexes, recursive calls to 
subroutines, and blanks in overpunched numeric fields. The CHECK qualifier format is: 

/CHECK[ = (option!,...])] 
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where option can be: 

[NOJBOUNDS 

[NOJRECURSION 

[NO]BLANKS_IN_NUMERICS 

ALL 

NONE 

where: 

BOUNDS Checks array indexes to make sure they are within array 

boundaries specified by the program. 

RECURSION Verifies that subroutines are not called recursively. 

BLANKS_IN_NUMERICS Converts blanks in overpunched numeric fields to zeros. 

ALL Indicates that RECURSION, BOUNDS, and 

BLANKS_IN_NUMERICS checking will be performed. 

NONE Indicates that RECURSION, BOUNDS, and 

BLANKS_IN_NUMERICS checking will not be performed. 

Specifying CHECK is equivalent to specifying CHECK = ALL; NOCHECK is equivalent 
to CHECK = NONE. NOCHECK is the default. 

Use CHECK = (RECURSION,BOUNDS) for programs only during initial program debug¬ 
ging, because compiling with this qualifier results in additional code and, consequently, 
takes more time to process. Using NOCHECK means that the compiler does not signal an 
error for an array reference outside the bounds of an array or for a subroutine that has 
been called recursively. Therefore, using NOCHECK may result in your program getting a 
memory-management or access-violation error at run time. 

2.1.2.2 CROSSJREFERENCE 

The CROSS-REFERENCE qualifier causes the compiler to include cross-reference infor¬ 
mation in the listing file for the compiled source file. Cross-reference information lists 
variable names, indicators, and the program lines in which they were referenced. Its for¬ 
mat is: 

/CROSS-REFERENCE 

When you use CROSS-REFERENCE, you must also use LIST, or LIST must be in effect 
(default for batch mode) to produce a listing file. NOCROSS-REFERENCE is the default. 
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2.1.2.3 DEBUG 

The DEBUG qualifier causes the compiler to provide information for the VAX Symbolic 
Debugger and the system run-time error traceback mechanism. Its format is: 

/DEBUG[ = (option[,...])] 

where option can be: 


[NO]SYMBOLS 

[NO]TRACEBACK 

ALL 

NONE 

where: 


SYMBOLS Causes the compiler to provide the debugger with local symbol defini¬ 
tions for user-defined names (including dimension information for 
arrays). If you use SYMBOLS, you can refer to data entities by their 
names when you use the debugger. 

TRACEBACK Causes the compiler to provide an address correlation table so that the 
debugger and the run-time error traceback mechanism can translate 
absolute addresses into source program routine names and line numbers. 


ALL 

NONE 


Causes the compiler to provide both local symbol definitions and an 
address correlation table. 

Prevents the compiler from providing debugging information. 


Neither the TRACEBACK qualifier nor the SYMBOLS qualifier affects a program’s exe¬ 
cutable code. 


Specifying DEBUG is equivalent to specifying DEBUG = ALL; NODEBUG is equivalent 
to DEBUG = NONE. DEBUG = TRACEBACK is the default. For information on debug¬ 
ging, see Part I, Chapter 10. 


2.1.2.4 LIST 

The LIST qualifier controls whether or not RPGII produces a listing file for the compiled 
program. The listing file contains the source program and a compilation summary. If you 
also use the MACHINE_CODE qualifier, the listing file will include the compiler-gener¬ 
ated object code for the compiled program. If you also use the CROSS-REFERENCE quali¬ 
fier, the listing file will include cross-reference information. The format of the LIST 
qualifier is: 

/LIST[=file-spec] 

You can include a file specification for the listing file. Otherwise, the output file defaults to 
the name of the first source file and the file type LIS. 
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If the RPG command is executed in interactive mode, the default is NOLIST. If the RPG 
command is executed in batch mode, the default is LIST. 

The listing file uses a listing page length which depends on the logical SYS$LP_LINES. 
Any value between 30 and 255 can be used for SYS$LP_LINES. The listing page length 
uses 3 line top and bottom margins. If the logical SYS$LP_LINES is not defined, the 
default page length will be 66 lines (60 listing lines after the 3 line top and bottom margins 
are subtracted). 

2.1.2.5 MACHINE.C0DE 

The MACHINE_CODE qualifier specifies that the listing file include the compiler-gener¬ 
ated object code. Its format is: 

/MACHINE-CODE 

When you use MACHINE_CODE, you must also use LIST, or LIST must be in effect 
(default for batch mode) to produce a listing file. NOMACHINE_CODE is the default. 

2.1.2.6 OBJECT 

The OBJECT qualifier causes RPG II to produce an object module, and optionally specifies 
its file name. Its format is: 

/OBJECT[ = file-spec] 

The default is OBJECT. 

By default, the compiler generates object files as follows: 

• If you specify one source file, RPG II generates one object file. 

• If you specify multiple source files separated by plus signs, RPG II appends the files 
and generates one object file. 

• If you specify multiple source files separated by commas, RPG II compiles and gener¬ 
ates a separate object file for each source file. 

You can use both plus signs and commas in the same command line to produce different 
combinations of appended and separated object files. See examples in Section 2.1.2. 

To produce an object file with an explicit file specification, you must use the OBJECT qual¬ 
ifier, in the form OBJECT = file-spec. Otherwise, the object file has the same name as its 
corresponding source file, and the default file type OBJ. By default, the object file produced 
from appended source files has the name of the first source file specified. All other file speci¬ 
fication attributes (node, device, directory, and version number) assume the default 
values. 

During the early stages of program development, you may find it useful to suppress the 
production of object files until your source program compiles without errors. Use the 
NOOBJECT qualifier to do this. 
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2.1.2.7 SEQUENCE-CHECK 

The SEQUENCE_CHECK qualifier causes the compiler to check the line numbers in col¬ 
umns 1 through 5 of every program line to make sure they are in ascending line-number 
sequence. If the line numbers are not in sequence, the compiler issues a warning message. 
Its format is: 

/SEQUENCE-CHECK 

NOSEQUENCE_CHECK is the default. 

2.1.2.8 WARNINGS 

The WARNINGS qualifier allows you to specify whether RPGII displays information and 
warning messages. Its format is: 

/WARNINGS! = (option!,...])] 

where option can be: 

[NO]OTHER 

[NO]INFORMATION 

ALL 

NONE 

where: 

OTHER Causes RPG II to display warning messages. 

INFORMATION Causes RPG II to display information messages. 

ALL Causes RPG II to display both warning and information messages. 

NONE Prevents RPG II from displaying warning or information messages. 

Specifying WARNINGS is equivalent to specifying WARNINGS = ALL; NOWARNINGS is 
equivalent to WARNINGS = NONE. WARNINGS = (NOINFORMATION,OTHER) is the 
default. 

2.2 Linking and Running Programs 

The VAX Linker uses the object module produced by the RPG II compiler as input and 
produces an executable image file as output. This file has the same name as your program 
and the default file type EXE. 

When your program calls other programs — that is, when it is made up of more than one 
program module — the linker takes multiple object files and creates a single executable 
image from them. See Part 1, Chapter 9 for information on subprograms. 
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You use the LINK command to invoke the VAX Linker. The format of the LINK command 
is: 


L IN K C / c o mm a n d - q u a 1 if i e r ( s ) 3 file-spec-listC/file- c iualifier(s)] 

where: 

command-qualifier(s) Specifies output file options. Use DEBUG to provide information 
for the VAX Symbolic Debugger. See Part I, Chapter 10 for infor¬ 
mation on debugging RPG II programs. See the VAX/VMS 
Linker Reference Manual for information about other command 
qualifiers. 

file-spec-list Specifies a file or the files to be linked. 

file-qualifier(s) Specifies input file options. See the VAX/VMS Linker Reference 

Manual for information on file qualifiers. 

When you type LINK, the system prompts with: 

_File: 

Respond by typing the file specification(s). If multiple file specifications do not fit on a sin¬ 
gle line, type a hyphen (-) as the last character on the line and continue on the next line. 

For example, to link the object file created from the program FIRSTTRY in Section 2.1, 
type: 

$ LINK FIRSTTRY 

$ 

This command tells the linker to accept FIRSTTRY.OBJ as input, and to produce 
FIRSTTRY.EXE as output. Once the executable file has been created, you run it with the 
RUN command: 

$ RUN FIRSTTRY 

$ 


2.3 Interpreting RPG II Compiler Error Messages 

The format of an RPG II compiler error message is: 

fac-severity-IDENT 

where: 

fac Represents the facility. The facility is always RPG. 

severity Indicates the severity of the error. Severity can be I (information), W (warn¬ 
ing), E (error), or F (fatal). 

IDENT Represents the IDENT field. 
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The IDENT field of an RPGII compiler error message designates the error recovery action 
taken by the RPG II compiler. IDENT fields can have one of the following values: 

• SPEC-IGNORED 

The current specification is ignored. The resulting program, if nonfatal, acts as if the 
specification was not entered. 

• ENTRY-IGNORED 

The entry in the current field is ignored. The resulting program, if nonfatal, acts as if 
the field was blank. 

• DEFN-IGNORED 

The current definition of this field is ignored. The resulting program, if nonfatal, uses 
the previous definition. 

• CHAR_IGNORED 

The current character is ignored. The resulting program, if nonfatal, acts as if the 
column was blank. 

• FATAL 

No error recovery action can be taken. The severity level is always fatal. 

• ACCEPTED 

The compiler accepts the entry exactly as specified. 

• SEE_MESSAGE 

The error text contains the recovery action taken by the RPG II compiler. 

• O-ASSUMED 

The entry in the current field is ignored. The resulting program, if nonfatal, acts as if 
the field contained 0. 
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Chapter 3 

Using the RPGII Editor 


This chapter explains how to use the RPG II editor. You use the RPG II editor to create, edit 
and read (or simply view) RPG II programs. 

The RPG II editor is available on the VT100 family, VT200 family and VK100 (GIGI) 
terminals. 

The RPG II editor allows overstriking; that is, you can change a program line by placing 
the cursor in the column where you want to make a change and typing a new character, 
without affecting any characters to the right of the cursor. 

The cursor is represented as a box (1) in the examples throughout this chapter. 

All examples in this chapter assume a terminal page size of 24 lines, unless otherwise 
noted. 

3.1 RPG II Editor Qualifiers 

Invoke the RPG II editor by typing the RPG/EDIT command. To create a file, provide a file 
specification, as shown in the following example: 

$ RPG/EDIT FIRSTTRY 

You do not have to supply the file type .RPG, because it is the default. 

To edit or read a file, include the name of the file you want to edit or read when you invoke 
the RPG II editor. See Section 3.8.1 for an example. 

When you invoke the editor, if the number of columns (SET TERMINAL/WIDTH = m) is 
less than 80 or the number of lines (SET TERMINAL/PAGE = n) is less than 6, the editor 
will display the following message, then will exit: 

At least G lines and 80 columns on the screen are required 

See the VAX/VMS DCL Dictionary for information on the SET TERMINAL command. 
Note that the SET TERMINAL command must be done before invoking the editor. 
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If the file you specify when invoking the RPGII editor is a new file, the RPGII editor dis¬ 
plays the following message: 

File not f o und 

If the file you specify when invoking the RPG II editor is an existing file, the RPG II editor 
displays the message: 

n lines read f roftt file de vice:[dire c t o r v ]fi1en ame♦t y p e 5 ve rsion 

Finally, the RPG II editor displays the following message: 

Press the PF2 Key to Set help information 

If the terminal page size is fewer than 17 lines, the initial help message is not displayed. If 
HELP is requested using the HELP key or a SET HELP command in a startup command 
file, and the terminal page size is less than 17 lines, the following message is displayed and 
the usual HELP action will not be performed: 

At least 17 lines on the screen are required by the editor to provide HELP 

Table 3-1 lists the qualifiers that you can use with the RPG/EDIT command. If you precede 
a qualifier with NO, that qualifier is not in effect. 


Table 3-1: RPG/EDIT Command Qualifiers 


Qualifier 

Negative Form 

Default 

/COMMAND 

/NOCOMMAND 

/COMMAND 

/CREATE 

/NOCREATE 

/CREATE 

/JOURNAL 

/NOJOURNAL 

/JOURNAL 

/OUTPUT 

/NOOUTPUT 

/OUTPUT 

/READ_ONLY 

/N ORE AD_ONLY 

/N ORE AD_ONLY 

/RECOVER 

/NORECOVER 

/NORECOVER 

/START_POSITION 

/N OSTART_POSITION 

/START_POSITION 


Sections 3.1.1 through 3.1.7 describe these qualifiers and explain how to use them. 

3.1.1 COMMAND 

The COMMAND qualifier causes the editor to execute a specified file in the startup com¬ 
mand file. Its format is: 

/COMMAND! = file-spec] 

The RPG II editor will read commands from any file specified by COMMAND. Each com¬ 
mand in the specified file will be treated as if the COMMAND function was used. 
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COMMAND is present by default, with a default value of RPGINI. If NOCOMMAND is 
used, then no command file is executed. See Section 3.7.2 for information on startup com¬ 
mand files. 

3.1.2 CREATE 

The CREATE qualifier creates a file for the editing session. If the specified file already 
exists, that file is opened. Its format is: 

/CREATE[ = file-spec] 

CREATE is present by default. If NOCREATE is used, the file is not created. However, if 
the file already exists, it is opened. 

3.1.3 JOURNAL 

The JOURNAL qualifier creates a journal file for the current editing session. Its format is: 
/JOURNAL! = file-spec] 

If you should leave an editing session abnormally, you can use the journal file to re-execute 
all the commands you issued during the session. To do this, type the RPG/EDIT/RECOVER 
file-spec command. 

JOURNAL is present by default. If you do not provide a file specification with JOURNAL, 
the RPG II editor creates a journal file with the same name as your input file and the 
default file type JOU. 

3.1.4 OUTPUT 

The OUTPUT qualifier defines the name of the output file. Its format is: 

/OUTPUT! = file-spec] 

OUTPUT is present by default. If you do not provide a file specification with OUTPUT, the 
RPG II editor creates an output file with the same name and type as the input file, whose 
version number is one higher than the highest existing version of the input file. 

If you use NOOUTPUT, the RPG II editor does not create an output file. In this case, you 
must either use the QUIT command or specify a file specification with the EXIT command 
to leave the editor. 

3.1.5 READ.ONLY 

The READ-ONLY qualifier tells the RPG II editor not to create a journal file or an output 
file for the file you are currently editing. Its format is: 

/READ-ONLY 
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You can use READ-ONLY when you want to view a file without changing its contents. In 
this case, you must either use the QUIT command or specify a file specification with the 
EXIT command to leave the editor. 

NORE AD_ONLY is the default, and automatically creates a journal file and output file for 
the file you are currently editing (unless you leave the RPG II editor using the QUIT 
command). 

Using READ-ONLY has the same effect as using both the NOOUTPUT and the 
NOJOURNAL qualifiers with the RPG/EDIT command. 

3.1.6 RECOVER 

The RECOVER qualifier reads the commands from a journal file and re-executes all the 
edits you made during an editing session. Its format is: 

/RECOVER 

Once the recovery is done, the RPG II editor responds with: 

Recovery complete 

At this time, you can continue editing your file. 

If the name of the recovery journal file is different from the default (the same file name as 
the input file with the JOU file type), use JOURNAL = file-spec and RECOVER to specify 
another name, as shown in the following example: 

$ RPG/EDIT/J0URNAL=FILE1.JQU/RECOVER FILEZ♦RPG 

In this example, the journal file name is FILE1.JOU and the name of both the input and 
output files is FILE2.RPG. If you do not use JOURNAL, the journal file name is 
FILE2.JOU. 

NORECOVER is the default. 

3.1.7 START_P0SITI0N 

The START-POSITION qualifier determines where the VAX RPG II editor starts in the 
editing buffer. Its format is: 

/START_POSITION[ = (line,column)] 

START-POSITION is the default. The setting is line 1, column 1. 

NOSTART-POSITION is equivalent to START-POSITION - (1,1) 
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3.2 The RPGII Editor Screen 

The RPG II editor screen consists of the following: 

• The help window 

• An 80-column ruler 

• Tab stops 

• The editing window 

• The Prompt line 

• The Message line 

Note that when you use a terminal without scrolling regions (for example, VK100 (GIGI)), 
the RPG II editor must redisplay the information on the screen rather than scrolling new 
information onto the screen. 
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The screen below shows an example of each of the above listed items. Note that all screens 
shown are based on a default setting of 24 lines with a top ruler. If you want to change the 
page size, see the SET TERM/PAGE commands in the VAX/VMS DCL Dictionary. 



PF1/PF2 - RPG II specification formats +-+-+-+-+ 

Press the PF1/KP7 key and type HELP for I Gold I Help IFnx FndIDlL UdLI 

information on commands and functions. +-+-+-+-+ 

For help on a specific key, press the I Pag CmdISec DspIRev MovIDlF UdFI 

PF2 key followed by the key for which +-+-+-+-+ 

you want help information. lAdv BotIBck Top I Cut PasIShL ShRI 

Other keys: BS.KEY DEL-KEY +-+-+-+-+ 

TAB_KEY UP,DOWN,LEFT,RIGHT IFld lEol DEI IChr Col I I 

CTRL-R-KEY CTRL_U_KEY +-+-+-+Ent I 

CTRL-U.KEY CTRL.Z.KEY I Lin OpL ISel Res I I 

+ - + - + - + 




help 




window 


0I1I2I3I4I5I6I7 

1234567890123456789012345678901234567890123456789012345678901234567890123456789 


# .. # .... 

H#++ 

H# FUNCTIONAL DESCRIPTION: 

This program produces a report of shipments for various 
products broken down by division and department using an 
input file with the shipment data for the past 4 quarters. 


H# 

H# 

H# 

H*~ 

H 

FSHIPS 


IP F 


41 


DISK 


8 0-co1umn 
ruler 

tab stops 

source window 


p r omp t line 
message line 
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When you use the HELP function (default = PF2), the help window appears on the screen. 
It includes a diagram of the keypad and other key functions. 

When the keypad diagram is displayed and you enter the HELP function again, the follow¬ 
ing message appears: 

Press the key for which you want further help information 

You can press the HELP key and any other key listed in the keypad diagram to display 
help information on that key in the help window. See Section 3.8.1 for an example. 

The HELP_SPECS function (default = PF1/PF2) causes the help window to display the 
specification format for the current line. See Section 3.8.1 for an example. See the 
DISPLAY function, Section 3.5.11, for information on how to remove HELP from the 
screen. 
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If you do not request help information, the RPGII editor displays the program in the entire 
screen except for the ruler and tab stops and the prompt and message lines, as shown in the 
following example: 



12345678901234567890123456789012345678901234567890123456789012345678901234567890 


.... 

I H#++ 

H* FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 
H# products broken down by division and department using an 


H# input file with the shipment data for 

the past 

4 quarters. 

H#-- 

H 

FSHIPS 

IP F 41 

DISK 



FSUMREP 

OF 98 

LPRINTER 



E 

QTY 

4 2 0 



LSUMREP 

55FL 500L 




ISHIPS 

I 

AA 01 

1 

5 DIV 

L2 

I 


6 

7 DEPT 

LI 

I 


8 

16 PROD 


I 


17 

24 QTY 


C* 

C 01 

XF00TQTY 

PR0QTY 

30 
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An 80-column ruler in reverse video is displayed above or below the source window. See 
Section 3.6.8.4 for information on setting the ruler. Below the ruler, a tab stop marks the 
beginning of each field for the specification of the current line. 

An asterisk (*) indicates a tab stop where you can enter a field value. A dot (.) indicates 
that the column must be left blank. A dash (-) after an asterisk indicates that the field 
must contain numeric data. Numeric data must be right-justified. Blanks after an asterisk 
indicate that the field must contain alphanumeric data. Alphanumeric data must be left- 
justified. 

The RPG II editor marks the line after the last line in the editing buffer with the End-of- 
Buffer [EOB] symbol. The [EOB] symbol will not appear in the output file. 

The last two lines of the screen consist of the prompt line and the message line. The prompt 
line displays prompts in reverse video for input when you use functions such as FIND and 
COMMAND. The message line displays informational and error messages. The following 
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example shows what the RPG II editor screen looks like with the specification format for 
the current line, the prompt for the FIND function, and an informational message. 



H 


Currency symbol 
I Inverted print (DIJ) 

I I Alternate collating sequence (SE) 
III IP forms position (i) 

III I 

III I 


o i I i 2 i 3 i 4 i 5 i 6 i T\ 

1234567890123456789012345678901234567890123456789012345678901234567890123456 


# ..... 

H*++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 


H*— 

H 

FSHIPS 

ip 

F 

41 

[Search for: 

i_ 



|New mail on 

node 

MYN0DE 

from SYSTEM! 
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3.3 The RPG II Editor Cursor 


The RPG II editor cursor is represented as a box (in reverse video) or an underscore, 
depending on the cursor setting for your terminal. The cursor is displayed in the current 
column on the current line. Note, however, that if the current column is column 81, the 
cursor is displayed in column 80 on the current line. If you try to move the cursor to the 
right of column 81 or to the left of column 1, the current column remains unchanged and 
one of the following messages is displayed in the message line: 

Attempt to m o u e past column 81 
Attempt to move before column 1 
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3.4 The RPGII Editor Buffers 

The RPG II editor uses the following four buffers: 

• Editing 

The editing buffer contains the file of source code that is displayed on the RPG II edi¬ 
tor screen. 

• Deleted-field 

The deleted-field buffer contains the field deleted when you use the DELETE_FIELD 
function (default = MINUS). See Section 3.5.14 for information on the 
DELETE_FIELD function. You can access the contents of the deleted-field buffer by 
using the UNDELETE_FIELD function. See Section 3.5.15 for information on the 
UNDELETE_FIELD function. 

• Deleted-line 

The deleted-line buffer contains the line deleted by the DELETE_LINE function 
(default = PF4). See Section 3.5.6 for more information on the DELETE_LINE func¬ 
tion. You can access the contents of the deleted-line buffer by pressing the 
UNDELETE_LINE (default = PF1/PF4). See Section 3.5.7 for more information on 
the UNDELETE-LINE function. 

• Paste 

The paste buffer contains the range of lines delimited by the SELECT (default = 
PERIOD) and CUT (default = KP6) functions (see Section 3.5.32). You can access the 
contents of the paste buffer by using the PASTE function (default = PF1/KP6). See 
Section 3.5.21 for more information on the PASTE function. 

3.5 Keys and Functions 

To make sure the RPG II editor is using the correct VMS terminal characteristics for your 
terminal, type the DCL SET TERM/INQUIRE command before invoking the RPG II edi¬ 
tor. The following diagram is a graphic representation of the RPG II editor keypad. 
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UTi00/UT200/UK 100(GIGI) K e ypad 


RPG II Editor Keypad 


PFl 

PF2 

PF3 

PF4 

7 

8 

9 

- 

a 

5 

G 

t 

i 


3 

Ente r 

o 

• 


Gold 

Help 

F n x F ri d 

D1L UdL 

P a a C frt d 

Sec Ds p 

Rev Mov 

DIF UdF 

Ad v Bo t 

!Bc K Top 

1 Cut Pas 

ShL ShR 

Fid 

Eol Del 

Chr Col 

E n t 

L i n 

OpI 

Se1 Res 


Chapter 3 refers to those keys with numbers and symbols as KPn, where KP means 
keypad and n is the number of the key shown on the VT100 family, VT200 family, and 
VK100 (GIGI) keypad. For example, KP6 refers to the keypad key numbered 6. Table 3-2 
lists the name and default function of each key. 

Note that many keys have alternate functions. An alternate function is enabled when you 
press the GOLD key (default = PF1) followed by the key you want to use. This sequence is 
referred to in this chapter as PFl/[key_name]. 


Table 3-2: RPG II Editor Define Key Defaults 


Command 

Key 

Default 

DEFINE KEY 

PFl 

GOLD 

DEFINE KEY 

UP 

UP 

DEFINE KEY 

DOWN 

DOWN 

DEFINE KEY 

LEFT 

LEFT 

DEFINE KEY 

RIGHT 

RIGHT 

DEFINE KEY 

PF2 

HELP_KEYPAD 

DEFINE KEY/GOLD 

PF2 

HELP_SPECIFICATIONS 

DEFINE KEY 

PF3 

FIND_NEXT 

DEFINE KEY/GOLD 

PF3 

FIND 

DEFINE KEY 

PF4 

DELETEJLINE 

DEFINE KEY/GOLD 

PF4 

UNDELETE_LINE 

DEFINE KEY 

KP7 

PAGE 

DEFINE KEY/GOLD 

KP7 

COMMAND 

DEFINE KEY 

KP8 

SECTION 

DEFINE KEY/GOLD 

KP8 

DISPLAY 

DEFINE KEY 

KP9 

REVIEW_ERROR 

DEFINE KEY/GOLD 

KP9 

MOVE_TO_RULER 

DEFINE KEY 

MINUS 

DELETE_FIELD 

DEFINE KEY/GOLD 

MINUS 

UNDELETE_FIELD 

DEFINE KEY 

KP4 

ADVANCE 

DEFINE KEY/GOLD 

KP4 

BOTTOM 

DEFINE KEY 

KP5 

BACKUP 

DEFINE KEY/GOLD 

KP5 

TOP 

DEFINE KEY 

KP6 

CUT 


(continued on next page) 

r 
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Table 3-2: RPGII Editor Define Key Defaults (Cont.) 


Command Key Default 


DEFINE KEY/GOLD 

KP6 

DEFINE KEY 

COMMA 

DEFINE KEY/GOLD 

COMMA 

DEFINE KEY 

KP1 

DEFINE KEY 

KP2 

DEFINE KEY/GOLD 

KP2 

DEFINE KEY 

KP3 

DEFINE KEY/GOLD 

KP3 

DEFINE KEY 

ENTER 

DEFINE KEY 

KPO 

DEFINE KEY/GOLD 

KPO 

DEFINE KEY 

PERIOD 

DEFINE KEY/GOLD 

PERIOD 

DEFINE KEY 

CTRLJHLKEY 

DEFINE KEY 

CTRL I KEY 

DEFINE KEY 

RETURN 

DEFINE KEY 

CTRL_R_KEY 

DEFINE KEY 

CTRL_U_KEY 

DEFINE KEY 

CTRL_W_KEY 

DEFINE KEY 

CTRL_Z_KEY 

DEFINE KEY 

DEL_KEY 

DEFINE KEY 

F10 

DEFINE KEY 

F12 

DEFINE KEY 

F15 

DEFINE KEY 

F16 

DEFINE KEY 

El 

DEFINE KEY 

E2 

DEFINE KEY 

E3 

DEFINE KEY 

E4 

DEFINE KEY 

E5 

DEFINE KEY 

E6 


PASTE 

SHIFTJLEFT 

SHIFT_RIGHT 

FIELD 

END_OF_LINE 

DELETE_TO_END_OF_LINE 

CHARACTER 

COLUMN 

ENTER 

LINE 

OPEN_LINE 

SELECT 

RESET 

FIELD_BACKWARD 

FIELD_FORWARD 

NEW_LINE 

REFRESH_SCREEN 

DELETE_TO_BEGINNING_OF_LINE 

REFRESH_SCREEN 

EXIT 

DELETE_CHARACTER 

EXIT 

FIELD_BACKWARD 

HE LP_KE YPAD 

ENTER 

FIND 

PASTE 

CUT 

SELECT 

SECTION_BACKWARD 

SECTION_FORWARD 


See DEFINE KEY (Section 3.6.2) for a complete list of definable keys. Sections 3.5.1 
through 3.5.44 describe these functions and explain how to use them. 
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3.5.1 The GOLD Function 


The GOLD function (default = PF1) enables you to select the alternate function of a key. 
In the following diagram of the keypad, the alternate key names appear on the right: 


Gold 

Help 

Fnx F n d 

D1L UdL 

P a s C m d 

Sec Ds p 

R e y Mou 

DIF UdF 

A d y B o t 

B c K Top 

Cut Pas 

ShL ShR 

Fid 

Eol DEI 

Chr Col 

-En t 

Lin 0 p L 

Se 1 Res 
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3.5.2 The HELP_KEYPAD Function 

The HELP_KEYPAD function (default = PF2) displays the keypad diagram in the help 
window, as shown in the following example: 



PF1/PF2 - RPG II specification formats +-+-+-+-+ 

Press the PF1/KP7 key and type HELP for I Gold I Help IFnx FndIDlL UdU 

information on commands and functions. +-+-+-+-+ 

For help on a specific key, press the IPag CmdISec DspIRev MovIDlF UdFI 

PF2 key followed by the key for which +-+-+-+-+ 

you want help information. IAdv BotIBck TopICut PasIShL ShRI 

Other keys: BS-KEY DEL-KEY +-+-+-+-+ 

TAB-KEY UP,DOWN,LEFT,RIGHT IFld lEol DEllChr Coll I 

CTRL-R.KEY CTRL-U-KEY +-+-+-+Ent I 

CTRL-U-KEY CTRL-Z-KEY I Lin OpL ISel Res I I 

+ - + -+-+ 


0 I 1 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# .. # ... 

I H*++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 
H#— 

H 

FSHIPS IP F 41 DISK 




ZK-4333-85 

If HELP is requested while the terminal page size is fewer than 17 lines, the following 
message will be displayed and the usual HELP action will not be performed: 

At least 17 lines on the screen are required by the editor to provide HELP 

HELP cannot be displayed unless there are enough lines on the screen to position the 
HELP window and still keep the ruler, prompt line, message line and one line of the edit¬ 
ing window visible. 


Using the RPG II Editor 3-13 








If the keypad diagram is already displayed, you can get help information on any function 
(except GOLD) by using HELP_KEYPAD (default = PF2) and the key for which you want 
help information. Help information will appear in the help window. The following exam¬ 
ple shows help on the CUT (default = KP6) and PASTE (default = PF1/KP6) functions: 



KP6 


The CUT function moves the selected range of lines to the paste buffer. The 
selected range of lines consists of the line identified by the SELECT 
function up to the current line. The line following the selected range of 
lines becomes the current line. The current column remains unchanged. 

The PASTE function inserts the contents of the paste buffer directly in 
front of the current line. The current line is moved down to accommodate 
the lines from the paste buffer. The current column and line remain 
unchanged._ 


I 0 I 1 I 2I 3 I 4 I 5 I 6 I 7 I] 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# .. # ... 

I H*++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 
H*— 

H 

FSHIPS IP F 41 DISK 



The HELP_SPECIFICATIONS function (default = PF1/PF2) displays the specification 
format for the current line. In the following example, if the current line is line 100, the 
RPG II editor displays the Control specification format when you use 
HELP_SPECIFICATIONS. 
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Currency symbol 
I Inverted print (DIJ) 

I I Alternate collating sequence (SE) 

III IP forms position (i) 

III I 

H ill I 


I 0 I i I 2I 3 I 4 I 5 I 6 I 7 M 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#......a..*....#.#... 

I 100H*++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 
H*— 

H 

FSHIPS IP F 41 DISK 
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To restore the editing buffer to the entire screen, as shown in the following example, use 
the DISPLAY function (default = PF1/KP8). 
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0 I i I 2 I 3 14 I 5 I 6 I o 7 J 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# ...... 

I H#++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 


H* input file with the shipment data for 

the past 4 quarters. 

H#— 

H 

FSHIPS 







IP F 

41 

DISK 




FSUMREP 

0 F 

98 

LPRINTER 




E 

LSUMREP 

55FL 500L 

QTY 

4 2 0 




ISHIPS 

I 

AA 01 


1 

5 

DIV 

L2 

I 



6 

7 

DEPT 

Li 

I 



8 

16 

PROD 


I 



17 

24 

QTY 


C# 







C 01 


XF00TQTY 

PR0QTY 

30 


C 01 

PR0QTY 

ADD DEPQTY 

DEPQTY 

30 
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The RPGII editor automatically updates the tab stops and the specification format, if dis¬ 
played, for the specification type of the current line after a terminator (such as TAB) is 
typed. 


3.5.4 The FIND JNEXT Function 

The FIND_NEXT function (default = PF3) moves the cursor to the first character position 
of the next occurrence of the search string, depending on the current direction (ADVANCE 
or BACKUP). Use the FIND function to enter the search string. If the current direction is 
ADVANCE, the RPG II editor will try to locate the next occurrence of the search string by 
searching forward from the current column and line to the end of the editing buffer. If the 
current direction is BACKUP, the RPG II editor will try to locate the next occurrence of the 
search string by searching backward from the current column and line to the beginning of 
the editing buffer. If the RPG II editor cannot locate the search string, the current column 
and line remain unchanged and an error message is displayed in the message line. See 
Section 3.8.2 for an example of the FIND_NEXT function. 
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3.5.5 The FIND Function 


The FIND function (default = PF1/PF3) locates the search string you specify. The RPGII 
editor moves the cursor forward or backward to the beginning of the nearest occurrence of 
the search string, depending on the current direction (ADVANCE or BACKUP). If the cur¬ 
rent direction is ADVANCE, the RPG II editor will try to locate the search string by 
searching forwards from the current column and line towards the end of the editing buffer. 
If the current direction is BACKUP, the RPG II editor will try to locate the search string by 
searching backwards from the current column and line towards the beginning of the edit¬ 
ing buffer. 

When you use the FIND function, the RPG II editor displays the following prompt in the 
prompt line: 

Search for: 

You can enter up to 63 characters for the search string. If no search string is entered, the 
RPG II editor will search for the last search string specified. Note that you cannot use con¬ 
trol characters (RETURN, FORM FEED, TAB, and so on) in the search string. 

If the RPG II editor cannot locate the search string, the current column and line remain 
unchanged and the following error message is displayed in the message line: 

String not f o und 

Terminate the search string by pressing either the RETURN key or the ENTER key. 

See Section 3.8.2 for an example of the FIND function. 

3.5.6 The DELETE.LINE Function 

The DELETE_LINE function places the current line in the deleted-line buffer, at the same 
time removing it from the screen. The line following the deleted line becomes the current 
line. The current column remains unchanged. If there is no line following the deleted line, 
the cursor is left in column 1 at the [EOB] mark. 

3.5.7 The UNDELETEJ.INE function 

The UNDELETE_LINE function (default = PF1/PF4) inserts the contents of the deleted- 
line buffer before the current line. The new line becomes the current line, and the current 
column remains unchanged. 

If the deleted-line buffer is empty, no action is taken but an error message is displayed in 
the message line. 


Using the RPG II Editor 3-17 



3.5.8 The PAGE Function 


The PAGE function (default = KP7) causes the editing buffer to move forward or back¬ 
ward, depending on the current direction (ADVANCE or BACKUP), to the next page. A 
page is the start or finish of a section with the same kind of specification type (column 6). 

In the following example, if the current cursor position is in column 34 on line 120, the 
current direction is ADVANCE, the current setting for the SET STARTCOLUMN com¬ 
mand is 7, and you use the PAGE function, the RPGII editor moves the cursor to column 7 
on line 170. 



12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # # # # # #— ### # # # 

10H#++ 

20H* FUNCTIONAL DESCRIPTION: 

30H# This program produces a report of shipments for various 
40H# products broken down by division and department using an 


50H* input file with the shipment data for 

the past 4 quarters. 

60H#— 






70H 






80FSHIPS 

IP F 

41 

DISK 



90FSUMREP 

0 F 

98 

LPRINTER 



100E 


QTY 

4 2 0 



110LSUMREP 

55FL 500L 





120ISHIPS 

AA 01 





1301 



1 

5 DIV 

L2 

1401 



6 

7 DEPT 

LI 

1501 



8 

16 PROD 


1601 



17 

24 QTY 


170CI 






180C 01 


XF00TQTY 

PR0QTY 

30 


190C 01 

PR0QTY 

ADD DEPQU 

' DEPQTY 

30 
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3.5.9 The COMMAND Function 

The COMMAND function (default = PF1/KP7) allows you to execute an RPG II editor 
command. The RPG II editor displays the following prompt: 

C o m (ti a n d z 
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The following commands can be entered: 

• COMPILE 

• DEFINE KEY 

• EXIT 

• HELP 

• INCLUDE 

• QUIT 

• RESEQUENCE 

• SET 

• SHOW 

• SUBSTITUTE 

Sections 3.6.1 through 3.6.10 describe these RPG II editor commands and explain how to 
use them. 

3.5.10 The SECTION Function 

The SECTION function (default = KP8) causes the editing buffer to move forward or back¬ 
ward the number of lines specified by the current setting of the SET SECTION command. 
The direction of the movement depends on the current direction (ADVANCE or BACKUP). 
The current column remains unchanged. See Section 3.6.8 for information on changing the 
SECTION value. See Sections 3.5.16 and 3.5.18 for information on setting the current 
direction. 

3.5.11 The DISPLAY Function 

The DISPLAY function (default = PF1/KP8) removes any help information from the 
screen. 

3.5.12 The REVIEW.ERR0R Function 

If you use the RPG II editor COMPILE command to compile your program, and your pro¬ 
gram contains errors, the RPG II editor moves the cursor to the column and line where the 
first error occurs, and displays the error text in the message line. The REVIEW_ERROR 
function (default = KP9) moves the cursor to the column and line where the next error 
occurs, and displays the error message for that error in the message line. You can edit the 
line to correct the error and use the REVIEW-ERROR function again to move the cursor to 
the next error. 
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If you use REVIEW_ERROR and there are no more errors, the RPGII editor displays the 
following message in the message line: 

No more errors found 

If you added or deleted a line in the program while correcting errors, the RPG II editor will 
display the following message when REVIEW_ERROR is used again: 

Reissue the editor COMPILE command 

3.5.13 The M0VE_T0_RULER Function 

The MOVE_TO_RULER function (default = PF1/KP9) places the cursor as close as possi¬ 
ble to the top of the ruler (if the editing window is above it) or towards the bottom of the 
ruler (if the editing window is below it). The current column remains unchanged. Move¬ 
ment is restricted to the boundaries of the SET SCROLL offsets. If the ruler is positioned 
above the editing window and the last line of the buffer appears, movement is stopped. If 
the ruler is positioned below the editing window and the first line of the buffer appears, 
movement is stopped. The MOVE_TO_RULER function will have no effect if no ruler is 
visible. 

3.5.14 The DELETE_FIELD Function 

The DELETE_FIELD function (default = MINUS) places all the characters between the 
cursor and the next field (forward or backward, depending on the current direction) into 
the deleted-field buffer and replaces the characters with spaces. 

3.5.15 The UNDELETE.FIELD Function 

The UNDELETE_FIELD function (default = PF 1/MINUS) replaces the current field with 
the contents of the deleted-field buffer. If the contents of the deleted-field buffer are longer 
than the current field, the RPG II editor just copies to the current field untill it is filled. 

If the contents of the deleted-field buffer are shorter than the current field, the RPG II 
editor fills the current field to the right with spaces. Also, the cursor moves to the next 
field, depending on the current direction (ADVANCE or BACKUP). 

3.5.16 The ADVANCE Function 

The ADVANCE function (default = KP4) sets the current direction to forward, that is, to 
the right and down, toward the end of the editing buffer. ADVANCE sets the direction for 
the following functions: 

• CHARACTER 

• DELETE_FIELD 
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• UNDELETE_FIELD 

• FIELD 

• END_OF_LINE 

• FIND 

• FIND_NEXT 

• LINE 

• PAGE 

• SECTION 

3.5.17 The BOTTOM Function 

The BOTTOM function (default = PF1/KP4) moves the cursor to the last line in the edit¬ 
ing buffer. The current column remains unchanged. 

3.5.18 The BACKUP Function 

The BACKUP function (default = KP5) sets the current direction to backward, that is, to 
the left and up, toward the beginning of the editing buffer. BACKUP sets the direction for 
the same functions that ADVANCE sets direction for. 

3.5.19 The TOP Function 

The TOP function (default = PF1/KP5) moves the cursor to the first line in the editing 
buffer. The current column remains unchanged. 

3.5.20 The CUT Function 

The CUT function (default = KP6) moves the selected range of lines to the paste buffer. 
The selected range of lines consists of the line identified by the SELECT function (default 
- PERIOD) to the current line. The line following the selected range of lines becomes the 
current line. The current column remains unchanged. If there is no line following the 
selected range, the cursor is left in column 1 at the [EOB] mark. See Section 3.8.2 for an 
example using CUT. 

3.5.21 The PASTE Function 

The PASTE function (default = PF1/KP6) inserts the contents of the paste buffer directly 
in front of the current line. The current line is moved down to accommodate the lines from 
the paste buffer. The current column and line remain unchanged. See Section 3.8.2 for an 
example using PASTE. 
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3.5.22 The SHIFTJ.EFT Function 

The SHIFTJLEFT function (default = COMMA) causes the following events to occur: 

• The character in the current column is deleted. 

• All characters to the right of the current column are moved one column to the left. 

• The cursor position remains the same. 

In the following example, if the cursor is in column 45 on line 350, and SHIFT_LEFT is 
used, the RPG II editor deletes the blank in column 45, moves all the characters to the 
right of the cursor one column to the left, and inserts a blank in column 80. 

Before using SHIFT_LEFT: 


011 121 314 I 5 161 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#» #*#** * # * ***—#* .... 

3500 48 |'Qi Q2 Q3 Q4 TOTAL' 

ZK-4337-85 


After using SHIFT_LEFT: 


0I1I2I3I4I5I6I 7I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#* *##** # # * ###—#* .... 

3500 48 HQ1 Q2 Q3 Q4 TOTAL' 

t 

cursor 

ZK-4338-85 

3.5.23 The SHIFT_RIGHT Function 

The SHIFT_RIGHT function (default = PF1/COMMA) causes the following events: 

• All characters in the current column through the end of the line are moved one col¬ 
umn to the right. 

• A space is placed in the current column. 

• The current column remains unchanged. 

In the following example, if the cursor is in column 44 on line 350, and SHIFT_RIGHT is 
used, the RPG II editor moves all characters one column to the right of the cursor and 
inserts a blank in column 44. The blank in column 80 is lost. 


3-22 Using the RPG II Editor 




Before using SHIFT_RIGHT: 


| 0 I i i 2I 3 I 4 I 5 I 6 I 7n 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


###—## .... 

48|Q1 Q2 Q3 Q4 TOTAL' 

t 

cursor 

ZK-4339-85 

After using SHIFT_RIGHT: 


I 0 I 1 i 2 I 3 i 4 I 5 I 6 I J il 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


*#*—## .... 

48|'Qi Q2 Q3 Q4 TOTAL' 

t 

cursor 
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3.5.24 The FIELD Function 

The FIELD function (default = KP1) moves the cursor to the nearest character in the next 
nonblank field. If the current direction is ADVANCE, using FIELD moves the cursor to the 
beginning of the next nonblank field following the current column. If the current direction 
is BACKUP, FIELD moves the cursor to the end of the next nonblank field preceding the 
current column. 

In the following example, if the cursor is in column 16 and the current direction is 
ADVANCE, FIELD moves the cursor to column 21. 


** ***** * * * 
3500 


** ***** * * * 
3500 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** 

IINPUT 


* *** *— *— 

A0 | 35 CA 


I cursor after 
cursor before 


. **—*—** 


****** .... 


ZK-4341-85 
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In the following example, if the cursor is in column 21 and the current direction is 
BACKUP, FIELD moves the cursor to column 16. 



## # ### #— #— # — .##— # — ## ####*# ..., 

IINPUT A0 | 35 CA 


I cursor before 
cursor after 


ZK-4342-85 


Note that you cannot use FIELD to move from one program line to another. 

3.5.25 The END_OF_LINE Function 

The END_OF_LINE function (default = KP2) moves the cursor one column to the right of 
the end of the current line (the last nonblank character) if ADVANCE is the current direc¬ 
tion. If the current direction is BACKUP, END_OF_LINE moves the cursor one column to 
the right of the end of the preceding line. 

If the cursor is already at the end of the current line and the current direction is 
ADVANCE, END_OF_LINE moves the current column one column to the right of the next 
line. 

In the following example, if the cursor is in column 45 and the current direction is 
ADVANCE, and if you use END_OF_LINE, the RPGII editor moves the cursor to column 
68 . 



## #*### # # # ###—## 


3500 


48 pi Q2 Q3 Q4 TOTAL'I 

t t 


cursor before 


cursor after 


ZK-4343-85 
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In the following example, if the cursor is in column 68 of line 350 and the current direction 
is BACKUP, and if you use END_OF_LINE, the RPGII editor moves the cursor to column 
54 in line 340. 


0 l i I 2 I 31 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


Q4 T0TAL'| 

cursor before 

rsor after 

ZK-4344-85 

3.5.26 The DELETE_T0_END_0F_LINE Function 

The DELETE_TO_END_OF_LINE function (default = PF1/KP2) deletes the characters 
from the current column to the end of the line. The cursor position remains unchanged. 

In the following example, if the cursor is in column 46 and you use 
DELETE_TO_END_OF_LINE, the RPG II editor deletes the characters in column 46 
through 67. 

Before using DELETE_TO_END_OF_LINE: 


0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** 

3500 
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***** * * 


***-** 

48 '01 Q2 Q3 Q4 TOTAL' 


cursor 


** 

3400 

3500 


***** * * 


***—** 


24 'PRODUCT'I 
48 'Qi Q2 Q 


After using DELETE_TO_END_OF_LINE: 


01 1 I 2 13 I 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


*# #*#** * # * #*#—#* .... 

3500 48 '| 

t 

cursor 

ZK-4346-85 
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3.5.27 The CHARACTER Function 


The CHARACTER function (default = KP3) moves the cursor position to the right or left, 
depending on the current direction (ADVANCE or BACKUP). If you attempt to move the 
cursor to the right of column 81 or to the left of column 1, no action is taken and an error 
message is displayed in the message line. 

In the following example, if the cursor is in column 47 and the current direction is 
ADVANCE, and if you use CHARACTER, the RPG II editor moves the cursor to column 
48. If the cursor is in column 47 and the current direction is BACKUP, and if you use 
CHARACTER, the RPG II editor moves the cursor to column 46. 


o I i I 2 I 3 I 4 I 5 I 6 I 7 | 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## 

3500 


***** * * 


***—## 

48 BiQ Q2 Q3 Q4 TOTAL' 

ftt 

(cursor after (ADVANCE) 
I cursor before 
cursor after (BACKUP) 
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3.5.28 The COLUMN Function 

The COLUMN function (default = PF1/KP3) highlights the number of the current column 
by causing the column number in the 80-column ruler to blink. The column function takes 
no action if no ruler is visible. 

On a terminal without AVO, the COLUMN function performs no action. 

On the VK100 (GIGI) terminal, the blinking for the COLUMN function is sometimes 
wider than the width of one character. 

3.5.29 The ENTER Function 

The ENTER function (default = ENTER) terminates the following entries: 

• The FIND function (see Section 3.5.5) 

• RPG II editor commands (see Section 3.5.9) 

The ENTER function also clears any information in the message line. 
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3.5.30 The LINE Function 


The LINE function (default = KPO) causes the cursor to move one line up or down, depend¬ 
ing on the current direction (ADVANCE or BACKUP). The cursor is moved to the current 
setting for the SET STARTCOLUMN command. 

3.5.31 The OPEN JJNE Function 

The OPEN_LINE function (default = PF1/KP0) creates a new line above the current line. 
The new line becomes the current line, and the cursor is moved to the current setting for 
the SET STARTCOLUMN command. If the current setting for the SET STARTCOLUMN 
command is greater than 6, the new line will have the same specification format as the 
previous line. See Section 3.8.2 for an example of the OPEN_LINE function. 

3.5.32 The SELECT Function 

The SELECT function (default = PERIOD) marks the current line as the beginning of the 
range of lines you are selecting (select range). The SELECT function highlights column 1 
of the current line in reverse video. You can use SELECT to select a range of lines to be 
deleted or moved. You can then use CUT to move the selected lines from the editing buffer 
to the paste buffer (see Section 3.5.20); and you can use PASTE to reinsert them into the 
editing buffer at another location (see Section 3.5.21). The cursor position in the line does 
not matter — the entire line will be moved into the paste buffer when CUT is used. 

If you select a line as the beginning of a select range and then delete that line, the select 
range will no longer be in effect and a message will be displayed in the message line. 

You cannot select the line where [EOB] appears. If you select a range of lines that includes 
[EOB], [EOB] will not be placed in the paste buffer. 

See Section 3.8.2 for an example of the SELECT function. 

3.5.33 The RESET Function 

You can clear the current setting for the SELECT function by using the RESET function 
(default = PF1/PERIOD). 

3.5.34 The UP Function 

The UP function (default = UP) causes the cursor to move up one line. The current column 
remains unchanged. If the current line is the first line in the editing buffer, the cursor will 
not be moved and an error message will be displayed. 
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3.5.35 The DOWN Function 


The DOWN function (default = DOWN) causes the cursor to move down one line. The cur¬ 
rent column remains unchanged. If the current line is the last line in the editing buffer, the 
cursor will not be moved and an error message will be displayed. 

3.5.36 The RIGHT Function 

The RIGHT function (default = RIGHT) moves the cursor to the right one column. If the 
current column is 80, the cursor is not moved and column 81 becomes the current column. 
If the current column is 81, the cursor will not be moved and an error message will be 
displayed. 

3.5.37 The LEFT Function 

The LEFT function (default = LEFT) moves the cursor to the left one column. If the cur¬ 
rent column is column 1, the cursor will not be moved and an error message will be 
displayed. 

3.5.38 The FIELD_BACKWARD Function 

The FIELD_BACKWARD function (default = BS_KEY) moves the cursor to the tab stop 
preceding the current column, or, if the cursor is before the first tab stop, moves the cursor 
to column 1. If the current column is 1, the cursor will not be moved and an error message 
will be displayed. 

3.5.39 The DELETE .CHARACTER Function 

The DELETE_CHARACTER function (default = DEL_KEY) replaces the character to 
the left of the cursor with a space and moves the cursor one column to the left. If you try to 
delete a character to the left of column 1, the cursor will not be moved and an error message 
will be displayed. 

3.5.40 The NEWSLINE Function 

The NEW_LINE function (default = RET_KEY) creates a new line following the current 
line. The lines following the current line are moved down to accommodate the new line. If 
the current line is the last line in the current buffer, a new last line is created. The cursor is 
moved to the current setting for the SET STARTCOLUMN command. If the current set¬ 
ting for the SET STARTCOLUMN command is greater than 6, the new line will have the 
same specification format as the previous line. 
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3.5.41 The FIELD_FORWARD Function 

The FIELD_FORWARD function (default = TAB_KEY) moves the cursor to the next tab 
stop after the current column. If the cursor has already passed the last tab stop, 
FIELD_FORWARD moves the cursor to column 81. If the current column is column 81, the 
cursor will not be moved and an error message will be displayed. 

3.5.42 The REFRESH.SCREEN Function 

The REFRESH_SCREEN function (default = CTRL_R_KEY and CTRL_W_KEY) 
rewrites the screen display. The cursor location remains unchanged. 

3.5.43 The DELETEJTO_BEGINMNG J)FJJNE Function 

The DELETE_TO_BEGINNING_OF_LINE function (default = CTRL_U_KEY) 
replaces the characters from the current column to column 1 with spaces. The cursor loca¬ 
tion remains unchanged. 

3.5.44 The EXIT Function 

The EXIT function (default = CTRL_Z_KE Y) writes the editing buffer to an output file as 
described in Section 3.1.2. If a journal file was created, it is not saved. 

If you have issued the RPGII editor COMPILE command, and then leave the RPGII editor 
using EXIT, the following message will be displayed: 

Subprocess terminated 

If you invoked the RPG II editor with the NOOUTPUT or the READ_ONLY qualifier, the 
following message will be displayed: 

Use EXIT with an output file specification or QUIT 

EXIT performs the same function as the EXIT/NOSAVE command. 


3.6 RPG II Editor Commands 

This section describes the RPG II editor commands and explains how to use them. You 
must issue the COMMAND function before executing an RPG II editor command. Section 
3.5.9 discusses the COMMAND function. 

The following conditions exist when executing RPG II editor commands: 

• If you type a command with a missing required parameter, you will get a prompt to 
supply the missing parameter. 
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• Qualifiers can appear anywhere on the line; they do not have to immediately follow 
the command and can appear in any order. 

• Qualifiers can be negated. 

• Command line input can be in uppercase, lowercase, or mixed case. 

• Abbreviations are allowed. You must type enough information to resolve any 
ambiguity. 

• You can enter full line comments, end of line comments, and blank lines in a command 
line. 

• You can continue a command line by entering a hyphen (-) at the end of the line. You 
will get a prompt for more input. 

• Terminate a command by pressing either the RETURN key or the ENTER key. 

3.6.1 The COMPILE Command 

The COMPILE command compiles the source code in the editing buffer, and displays both 
of the following messages: 

Subprocess activated 
Beginning compilation 

The message “Subprocess activated” appears only when the COMPILE command is issued 
for the first time during an editing session. 

The format of the COMPILE command is: 

COMPILE [/LIST] 

The following message is displayed indicating how many errors were found: 

Compilation complete--)*! errors found 

If n is 0, no errors were found and you can leave the editor, then link and run your program. 

If the compilation encounters errors, the error text associated with the first error is dis¬ 
played in the message line and the cursor is moved to the column and line where the first 
error occurs. If there is more than one error, use the REVIEW_ERROR function to move 
the cursor to the column and line causing the next error. See Section 3.5.12 for more infor¬ 
mation on the RE VIEW_ERROR function. 

You can use only the LIST qualifier with the COMPILE command to create a listing file for 
the compiled source code. The default is NOLIST. OBJECT is always in effect. However, if 
the compilation encounters fatal errors, an object module will not be produced. 
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You can specify a symbol definition at the DCL command level to change the defaults for a 
compilation. When you issue the RPGII editor COMPILE command, the compiler will use 
these settings. In the following example, the symbol RPG is defined to compile a program 
and generate a listing file with machine-generated code. The compiler will also generate 
code in the program to check for blanks in numerics. 

$ RPG :== RPG/LIST/MAC/CHECK:BLANKS-IN.NUMERICS 

To use the debugger after you enter the COMPILE command, you must first define the 
following command before invoking the editor: 

$ RPG := RPG/DEBUG 

See Part I, Chapter 10 for information on how to set the appropriate source file. 

The COMPILE command requires each line in the editing buffer to be 140 characters or 
less. 

If you define RPG to invoke something other than the RPG II compiler, or if the RPG II 
compiler encounters an unexpected error, the following message is displayed in the mes¬ 
sage line: 

Unexpected error during compilation - 1e a ve editor and try DCL RPG command 


3.6.2 The DEFINE KEY Command 

The DEFINE KEY command allows you to bind specific keys to specific RPG editor func¬ 
tions. These functions are listed with their default key definitions in Table 3-2 at the 
beginning of Section 3.5. 

The following keys are bindable in the RPG editor: 

• Control keys 

• Cursor keys 

• Editing keys (LK201 except Rainbow) 

• Function keys (LK201 except Rainbow) 

• Keypad keys 

• Gold versions of all these keys 

exceptions 

The following list contains seven control key restrictions. These are special functions of 
the VMS operating system. 

CTRI_C_KEY 

CTRL-O-KEY CTRI_T_KEY 

CTRI_Q_KEY CTRI_X_KEY 

CTRI_S-KEY CTRI_Y_KEY 
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Note that key redefinition does not cause automatic update to the editor keypad diagram 
and key-specific help text. 

The format of the DEFINE KEY command is: 

DEFINE KEY[/GOLD] key_name function 

In this command, /GOLD indicates that you must press GOLD followed by key_name to 
execute the chosen function. For example: 

DEFINE KEY/GDLD KPS CUT 

When you enter this command and then press the GOLD key, followed by the KP5 key, the 
CUT function is executed. 

If “key_name” is not a valid definable key, or if “function” is not a valid RPG editor func¬ 
tion that is bindable to a key, a message is displayed. 

To redefine the GOLD key, enter the following line at the command prompt: 

DEFINE KEY Keyname GOLD 

To remove the GOLD key completely, enter the following line at the command prompt: 

DEFINE KEY/GOLD PF1 GOLD 

Note that if you use a key name other than PF1 with this command, it will be treated as if 
PF1 had been entered. 

Note also that you must redefine the GOLD key (default = PF1) before you can define the 
PF1 key to a function other than GOLD. 

See Table 3-2 for a list of default key definitions. This table provides a list of definitions 
that are bindable to keys. Note that in some cases, more than one key is bound to the same 
procedure. Note also that TAB_KEY and CTRL_I_KEY (the default settings for 
FIELDJFORWARD), and the RETURN_KEY and CTRL_M_KEY (default settings for 
RETURN), can only be bound to the same function, while the F10 key and CTRL_Z_KEY 
(the default settings for EXIT) may be bound to separate functions. 

The SECTION_FORWARD and the SECTIONJBACKWARD functions are not bound by 
default to any key on the VT100 family and VK100 (GIGI) terminal keyboards. However, 
you can bind any of the valid definable keys to those functions. 
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Table 3—3 contains additional keys that are bindable to the functions listed in Table 3—2. 

Table 3-3: RPG KEYNAMES FOR VALID DEFINABLE KEYS 


RPG Keyname 

LK201 

VT100 Family 
VK100 (GIGI) 

PF1 

PF1 

PF1 

PF2 

PF2 

PF2 

PF3 

PF3 

PF3 

PF4 

PF4 

PF4 

KP0,KP1,...,KP9 

0,1,. ..,9 

0,1,...,9 

PERIOD 



COMMA 



MINUS 

- 

- 

ENTER 

Enter 

Enter 

UP 

Up-arrow 

Up-arrow 

DOWN 

Down-arrow 

Down-arrow 

LEFT 

Left-arrow 

Left-arrow 

RIGHT 

Right-arrow 

Right-arrow 

El 

Find/El 


E2 

Insert-here/E2 


E3 

Remove/E 3 


E4 

Select/E4 


E5 

Prev-screen/E5 


E6 

Next-screen/E 6 


HELP 

Help/F15 


DO 

D0/FI6 


F7,...,F20 

F7,...,F20 


TAB_KEY 

Tab 

Tab 

RET_KEY 

Return 

Return 

DEL_KEY 

O 

Delete 

LF_KEY 


Line-feed 

BS_KEY 


Back-space 

CTRL_A_KEY 

Ctrl/A 

CTRL/A 

CTRL_B_KEY 

Ctrl/B 

CTRL/B 

CTRL_Z_KEY 

Ctrl/Z 

CTRL/Z 


Note the list of exceptions at the beginning of this section. 

You can modify the key bindings shown in Table 3-2 at editor startup by creating a startup 
command file with the desired DEFINE KEY commands. See Section 3.7.2, Startup Com¬ 
mand Files, for more information on using DEFINE KEY. 
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3.6.3 The EXIT Command 


The EXIT command writes the editing buffer to the output file and leaves the RPGII edi¬ 
tor, returning to the DCL command prompt ($), as shown in the following example: 


0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#* # ### # - #- # - . ##-#-## # # # # # * .... 

10H#++ 

20H* FUNCTIONAL DESCRIPTION: 

30H# This program produces a report of shipments for various 

40H# products broken down by division and department using an 

50H# input file with the shipment data for the past 4 quarters. 

60H#— 

70H 

80FSHIPS IP F 41 

90FSUMREP OF 98 

100E QTY 

110LSUMREP 55FL 500L 
120ISHIPS AA 01 
1301 
1401 
1501 
1601 
170C* 

180C 01 XF00TQTY PR0QTY 30 

190C 01 PR0QTY ADD DEPQTY DEPQTY 30 


|53 records written to file MYDISK:CMYDIRECT0RY]MYFILE.RPG;2| 


DISK 

LPRINTER 
4 2 0 


1 5 DIV L2 

6 7 DEPT Li 

8 16 PROD 

17 24 QTY 


* I 
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The format of the EXIT command is: 

EXIT [/SAVE] [file-spec] 

The output file is one of the following: 

• The file name you supplied with the EXIT command 

• The file name you supplied with the OUTPUT qualifier to the RPG/EDIT command 

• The same file name as the input file you specified when you invoked the RPG II editor, 
if the READ-ONLY or the NOOUTPUT qualifiers were not used with the RPG/EDIT 
command 

The RPG II editor will write the editing buffer to the output file even if no changes have 
been made. 
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You can use the SAVE qualifier with the EXIT command to save the journal file, if one was 
created. The file name of the journal file is the name of the output file, if specified, with the 
JOU file type. If a journal file name was not specified, the RPGII editor uses the same file 
name as the input file. See Section 3.1.3 for information on journal files. 

If an error occurs during the execution of an EXIT/SAVE command and you resume edit¬ 
ing, the journaling facility will still be in effect. 

If you have issued the RPG II editor COMPILE command and then leave the RPG II editor 
by typing the EXIT command, the following message will be displayed in the message line: 

Subprocess terminated 

3.6.4 The HELP Command 

The HELP command displays information on RPG II editor functions and commands in 
the help window of the RPG II editor screen. The following example shows what the screen 
looks like after you issue the COMMAND function, type the HELP command, and press 
either the RETURN key or the ENTER key: 



read this help information while using the editor by typing the HELP 
command. 


Additional information available: 

Commands Cursor Functions Help Journal Keypad Specs 


| o i i i 2 i 3 i 4i 5 i 6 i i n 

[123456789012345678901234567890123456789012345678901234567890123456789012345678901 


#. ... # .... . . . 

| 10H#++ 

20H* FUNCTIONAL DESCRIPTION: 

30H# This program produces a report of shipments for various 

40H# products broken down by division and department using an 

50H# input file with the shipment data for the past 4 quarters. 
60H#— 

70H 

80FSHIPS IP F 4i DISK 



ZK-4349-85 
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The format of the HELP command is: 

HELP [/FULL] [/PAGE] [/PROMPT] list-of-topics 

The PAGE qualifier is similar to the DCL HELP command PAGE qualifier. If the help text 
does not fit in a logical page (in this case, the help window), the text is displayed a page at a 
time and you must enter a RETURN to advance to the next page. The default is NOPAGE. 

The PROMPT qualifier is similar to the DCL HELP command PROMPT qualifier. Once 
help for the given list of topics is displayed, you are prompted for additional topics, which 
are then linked to the current list of topics. Press RETURN repeatedly to back up through 
the levels of help text. CTRL/Z terminates the HELP command. The default is 
NOPROMPT. 

The FULL qualifier uses the entire screen, except for the prompt and message lines, to 
display help text. When the requested help has been displayed, the previous screen layout 
is restored. You are prompted to enter a RETURN before the screen is repainted. If the 
previous screen contained help text, it is not restored. Instead, the last 11 lines of text from 
the current HELP is left in the help window. The default is NOFULL. 

Note that FULL, PAGE and PROMPT are positional qualifiers. If they occur after a topic 
or subtopic, they are interpreted as subtopics on which help is desired. 

There is no fixed number on the list of topics. Whatever can fit on the command line is 
valid. If you use the PROMPT mode, you can extend the depth indefinitely. 

By default, the RPGII editor searches its own help library (SYS$HELP:RPGEDIHLP) for 
the given list of topics. 

You can access other libraries in the following ways: 

• If the first topic has the form @filespec, that library is searched instead. 

• If you define logical names of the form HLP$LIBRARY, HLP$LIBRARY_1, ..., 
HLP$LIBRARY_999, the LIBRARIAN searches them in the following order: root 
library, main library, process libraries, group libraries, and system libraries. 
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The following example shows what the screen looks like after you issue the COMMAND 
function, type HELP COMMANDS, and press either the RETURN key or the ENTER key: 



Editor commands are executed by pressing the COMMAND function (PF1/KP7 - see 
information for FUNCTIONS). Any command, parameter or qualifier can be 
abbreviated so that the information typed is unambiguous. The prompt 
"Command: " is displayed in reverse video on the prompt line. Any 
characters that can normally be typed in the editor may be typed at the 
prompt. 

Qualifiers can be negated and can also appear in any order on a command line 
after the name of the command. 

Blank command lines are ignored. Also any text on a command line after an 
exclamation point ("!") is ignored. 


Additional information available: 

COMPILE DEFINE EXIT HELP INCLUDE QUIT RESEQUENCE 

SET SHOU SUBSTITUTE 


0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# .......#....... 

| 10H*++ 

20H# FUNCTIONAL DESCRIPTION: 

30H# This program produces a report of shipments for various 

40H# products broken down by division and department using an 

50H# input file with the shipment data for the past 4 quarters. 
60H#— 
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After you press either the RETURN key or the ENTER key to execute a HELP command 
and help information is displayed, the RPG II editor returns the cursor to its current col¬ 
umn and line so you can resume editing. 


3.6.5 The INCLUDE Command 

The INCLUDE command copies a text file into the source buffer using the VAX RPG II 
editor. The format of the INCLUDE command is: 

INCLUDE file-spec 

The file is copied into the editing buffer, immediately before the current line. The cursor 
position remains unchanged. Note that the lines read in are not syntax checked. 
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If the INCLUDE is successful, the number of records read in is displayed on the message 
line. 


3.6.6 The QUIT Command 

The QUIT command allows you to leave the RPG II editor and return to DCL command 
level, without writing the editing buffer to the output file, as shown in the following 
example: 



10H*++ 

20H# FUNCTIONAL DESCRIPTION: 

30H# This program produces a report of shipments for various 
40H# products broken down by division and department using an 


50H# input file wi 
60H#— 

70H 

80FSHIPS IP F 
90FSUMREP 0 F 
100E 

UOLSUMREP 55FL 500L 
120ISHIPS AA 01 
1301 
1401 
1501 
1601 
170C* 

180C 01 

190C 01 PR0QTY 


iCommand: QUITI 


the shipment data for 


41 DISK 

98 LPRINTER 

QTY 420 


1 

6 

8 

17 

XF00TQTY PRQQTY 

ADD DEPQTY DEPQTY 


the past 4 quarters. 


5 DIV L2 
7 DEPT LI 
16 PROD 
24 QTY 

30 

30 



ZK-4351-85 


The format of the QUIT command is: 

QUIT [/SAVE] 

Use the QUIT command if you have made no changes to the editing buffer or if you have 
decided not to save the changes you made. If you have made changes, or if you have pressed 
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keys to move the cursor past the last nonblank character in any line, the RPG II editor 
displays the following message: 

The current buffer m a y haue bee n modified# do you r e a 1 1 y w ant to quit? 

You can respond with Y, YE, or YES. Any other response will continue the editing session. 
If you resume editing, a journal file for your edits will not be created. To resume journaling, 
you must leave the RPG II editor, and invoke the RPG II editor again. 

You can use the SAVE qualifier with the QUIT command to save the journal file, if one was 
created. 

If you have issued the RPG II editor COMPILE command and then leave the RPG II editor 
by typing the QUIT command, the following message will be displayed in the message line: 

Subprocess terminated 


3.6.7 The RESEQUENCE Command 

The RESEQUENCE command either generates a new line number for each program 
line in the editing buffer or resequences existing line numbers. The format of the 
RESEQUENCE command is: 

RESEQUENCE [/REMOVE] [initial-value [increment]] 

The RESEQUENCE command renumbers program lines up to the first line containing the 
delimiter //blank or **blank in columns one through three. Lines are numbered beginning 
at initial-value (default =10) and incrementing by the increment value (default = 10). 

The maximum line number is 99,999. If, during resequencing, a line number plus the 
increment exceeds 99,999, that line and all remaining lines are numbered 99,999. In this 
case, reissue the RESEQUENCE command with smaller values for initial-value and 
increment. 

The RESEQUENCE/REMOVE command will remove all line numbers in the editing 
buffer. 

The following command will renumber the line numbers in the editing buffer beginning 
with 100 and increment each number by 20: 

RESEQUENCE 100 20 

See Section 3.8.2 for another example of the RESEQUENCE command. 
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3.6.8 The SET Command 


The SET command controls RPG II editor options. Once set, these options are in effect 
until you leave the RPG II editor or reissue the SET command. 

You can include SET commands in a startup command file. See Section 3.7.2 for 
information. 

The format of the SET command is: 

SET option 

RPG II editor options include: 

• COMMAND 

• DEFAULT 

• HELP 

• RULER 

• SCROLL 

• SECTION 

• STARTCOLUMN 

• SYNTAXCHECK 

3.6.8.1 The COMMAND option 

The COMMAND option allows you to process additional startup command files at the 
beginning of the RPG II session. The format of the COMMAND option is: 

SET COMMAND file-spec 

See Section 3.7.2, Startup Command Files, for information on the SET COMMAND 
option. 

3.6.8.2 The DEFAULT option 

The DEFAULT option allows you to determine the default value of qualifiers used in other 
editor commands. The format of the DEFAULT option is: 

SET DEFAULT option 

For example, the command: 

SET DEFAULT PAGE t PROMPT 

means that any later HELP command uses the PAGE and PROMPT options by default. 
You can turn defaults off by using the negated form of a qualifier. (For example, SET 
DEFAULT NOPROMPT.) 
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3.6.8.3 The HELP option 

The HELP option allows you to choose a variety of settings. The format of the HELP option 
is: 


SET HELP {KEYPAD I NONE I SPECIFICATIONS} 

The HELP KEYPAD option acts as if you used the HELP_KEYPAD function (default = 
PF2). See Section 3.5.2 for information on HELP_KEYPAD. 

The HELP NONE option allows you to start up as if you have used the DISPLAY function. 
See Section 3.5.11 for information on DISPLAY. 

The HELP SPECIFICATIONS option acts as if you used the HELP_SPECIFICATIONS 
function (default = PF1/PF2). See Section 3.5.3 for information on 

HELP_SPECIFICATIONS. 

3.6.8.4 The RULER option 

The RULER option moves the three-line 80-column ruler with tab stops as a unit, to either 
the top or bottom of the current window. SET RULER NONE removes the ruler from the 
screen. 

The format of the RULER option is: 

SET RULER {TOP I BOTTOM I NONE} 
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The example below shows an editor screen as it appears after a SET RULER BOTTOM 
command, with an 18-line terminal page size. The next example shows the same screen 
followed by a help request. 



I 


FSHIPS IP F 41 

FSUMREP OF 98 

E QTY 

LSUMREP 55FL 500L 
ISHIPS AA 01 
I 
I 
I 
I 

C# 

C 01 
C 01 

c# 


DISK 

LPRINTER 
4 2 0 


1 5 DIV L2 

6 7 DEPT LI 

8 16 PROD 
17 24 QTY 

PROQTY 30 
DEPQTY 30 


XF00TQTY 

PROQTY ADD DEPQTY 



## # #** #— #— #— . ##—#—## ###### .... 



ZK-4352-85 
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PF1/PF2 - RPG II specification formats +-+-+-+-+ 

Press the PF1/KP7 key and type HELP for I Gold I Help IFnx FndIDlL UdU 

information on commands and functions. +-+-+-+-+ 

For help on a specific key, press the IPag CmdISec DspIRev MovIDlF UdFI 

PF2 key followed by the key for which +-+-+-+-+ 

you want help information. IAdv BotIBck TopICut PasIShL ShRI 

Other keys: BS-KEY DEL-KEY +-+-+-+-+ 

TAB-KEY UP,DOWN,LEFT,RIGHT IFld lEol DEllChr Coll I 

CTRL-R-KEY CTRL-W-KEY +-+-+-+Ent I 

CTRL-U-KEY CTRL-Z-KEY I Lin OpL ISel Res I I 

+ - + - + - + 

| I 67 DEPT LI 


12345678901234567890123456789012345678901234567890123456789012345678901234567 


## # #*# #— #— # — .## — # — ## ###### .... 
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3.6.8.5 The SCROLL option 

The SCROLL option specifies the region within the editing window where the cursor will 
stay. 

The format of the SCROLL option is: 

SET SCROLL [top-offset [bottom-offset]] 

Top-offset is the number of lines from the top of the editing window to the top of the scrol¬ 
ling region. Bottom-offset is the number of lines from the bottom of the scrolling region to 
the bottom of the editing window. If bottom-offset is omitted, the current offset from the 
bottom is not changed. If the top and bottom offsets are omitted, both offsets are set to the 
initial editor defaults of zero. 
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If you enter SET SCROLL 0 1, then the cursor will move from the line next to the ruler on 
the top, to within one line above the bottom of the editing window. If you want to keep the 
cursor from hitting the top line, enter a number greater than zero for top-offset. The higher 
the number, the greater the number of source code lines that will remain on the screen 
between the cursor and the top or bottom of the editing window. 

3.6.8.6 The SECTION option 

The SECTION option specifies the number of lines the RPGII editor will move the cursor 
(forward or backward) when the SECTION function (default = KP8) is used and there is 
no help information displayed. You can specify any value between one, and five less than 
the terminal page length. By default, the bottom line of the editing window moves to the 
top (just under the tab stops), regardless of the size of the window. 

The format of the SECTION option is: 

SET SECTION lines 

If you specify a SECTION value other than the default, the SECTION value, when help is 
displayed, is proportional to the visible number of lines in the editing window. 

3.6.8.7 The STARTCOLUMN option 

The STARTCOLUMN option specifies the current column for the following functions: 

• NEW_LINE 

• OPENJLINE 

• LINE 

• PAGE 

The format of the STARTCOLUMN option is: 

SET STARTCOLUMN column 

The default value is column 7. When the setting for the STARTCOLUMN qualifier is 
greater than 6, the RETURN key and OPEN_LINE (default = PF1/KP0) function supply 
the same specification type in column 6 as is present in the current line. 

3.6.8.8 The SYNTAXCHECK option 

The SYNTAXCHECK option specifies that syntax checking and automatic right justifica¬ 
tion of numeric fields will occur. 

The format of the SYNTAXCHECK option is: 

SET SYNTAXCHECK {ON I OFF I PROMPT} 
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By default, the RPG II editor starts up with the SYNTAXCHECK option on. This setting 
can be changed in a startup command file, or interactively. 

If you modify a line when syntax checking is on, and then attempt to move off the line, one 
of the following will occur: 

• If there are no errors on the line, and all numeric entries are properly justified, the 
requested action takes place. 

• If there are no errors on the line, but one or more numeric entries are not properly 
justified, the numeric entries are justified, the justified fields are highlighted, and the 
requested action takes place. The highlighting is removed from the field(s) when the 
next line is syntax checked. 

• If a syntax error is detected, the requested action does not take place. The cursor is 
positioned at the column of the error, and the error message is displayed on the mes¬ 
sage line. You can either correct the error, or ignore the error by immediately moving 
off the line. Another syntax check will take place on that line only if you modify it 
again. 

If you enter table and array data while SYNTAXCHECK is on, there is a risk that the data 
will be right-justified as if it were part of the source program, yielding unexpected results. 
Therefore, it is recommended that SYNTAXCHECK be set off while entering table and 
array data, or that you use the PROMPT option. When PROMPT is in effect, the editor will 
highlight any proposed numeric right justification before the justification is actually done, 
and will prompt you to see if you want it done. 

3.6.9 The SHOW Command 

The SHOW command displays the current settings for the following options: 

• DEFAULT 

• SCROLL 

• SECTION 

• STARTCOLUMN 

• SYNTAXCHECK 

• VERSION 

The format of the SHOW command is: 

SHOW option 
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The current settings appear in the message line, as shown in the following examples: 

COMMAND: SHOW DEFAULT PAGE * PROMPT 
Current defaults are NOPAGE*NOPROMPT 

Command: SHOW SCROLL 

Scroll offset from top is 0 * from bottom is 0 
Command: SHOW SECTION 

Section length is: 18 or when HELP is displayed: 7 

Command: SHOW STARTCOLUMN 
STARTCOLUMN value is: 7 

Command: SHOW SYNTAXCHECK 
SYNTAXCHECK is ON 

The VERSION qualifier displays the current version of the RPG II editor and a VAX 
RPGII copyright statement, as shown in the following example: 

Command: SHOW MERSION 

MAX RPG II M2♦0 editor COPYRIGHT (C) DIGITAL EQUIPMENT CORPORATION 1385 

3.6.10 The SUBSTITUTE Command 

The SUBSTITUTE command allows you to substitute text using the VAX RPG II editor. 
The format of the SUBSTITUTE command is: 

SUBSTITUTE search-argument replace-argument [/SELECT] [/QUERY] 

The SUBSTITUTE command replaces all occurrences of the search-argument with the 
replace-argument in the specified range. If SELECT is specified, the command applies to 
all lines in the select range. Otherwise, it applies to all lines in the buffer. 

Only exact matches of the search-argument with text in the editing buffer are performed. 

Only equal length substitutions are performed. If one argument is shorter than the other, 
it is padded on the right with spaces before searching and replacing begins. 

If you specify QUERY, then at each occurrence of the string to be substituted the following 
occurs: 

• The string to be substituted is highlighted. 

• A “Substitute this occurrence (YES, NO, ALL, or QUIT)? ” prompt is displayed on the 
prompt line. 

• You may answer YES, NO, ALL, or QUIT. 

• If you answer YES, the text is replaced and the editor finds the next occurrence. 

• If you answer NO, the text is not replaced and the editor finds the next occurrence. 
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• If you answer ALL, the current text is replaced as well as any further occurrences of 
the text, without additional prompting. 

• If you answer QUIT, the text is not replaced and the SUBSTITUTE command 
terminates. 

• If you make any other response, the above sequence is repeated from the point where 
the prompt message is displayed. 

If SYNTAXCHECK is on, the current line is syntax checked after each change is made. If a 
syntax error is found, the substitution is terminated. 

The command does not display the lines in which substitutions are made (except in 
QUERY mode). 

Upon completion of this command, the message “Substitutions: n” is displayed in the 
message area, where ‘n’ indicates the number of substitutions performed. 

Upon completion of this command when SELECT was specified, the select range is 
removed. 

The SUBSTITUTE command ignores the current editing direction. It always proceeds 
from the beginning of the range to the end. The current editing direction is not changed, it 
is just ignored for the duration of the command. 

The cursor is returned to where it was before the command was issued. 

Rules for specification of search-argument and replace-argument 

• The search-argument must contain at least one non-blank character. If it does not, the 
message “The search string must contain at least one non-blank character” is dis¬ 
played in the message area. 

• If lowercase characters are desired in the substitution, the argument must be 
enclosed within double quotation marks (for example, “string”). Otherwise, lowercase 
characters are converted to uppercase. 

• If the argument contains a terminator, such as a blank space or a slash (/), the argu¬ 
ment must be enclosed within double quotation marks (for example, “ ” and “/”). 

• If the argument contains a double quotation mark, two double quotation marks must 
be entered. 

• Single quotation marks are not treated like double quotation marks. 

• Control characters cannot be entered in arguments. 
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3.7 Customizing the Editor 

This section discusses several RPG II editor commands that are available to you. These 
commands enable you to customize your editing environment. 


3.7.1 Using Editor Commands 

For the purpose of this example, assume that you want the ruler to lie on the bottom of the 
screen and the keypad help to show in the help window. Because you are entering a pro¬ 
gram with a compile-time table or array, you would like to be prompted before any numeric 
fields are right-justified. Because you have chosen a small scrolling region, you would like 
the SECTION function to give you 10 lines. Finally, you would like to use CTRL/P to 
review errors. 

You would use the COMMAND function (default = PF1/KP7) to enter each of the follow¬ 
ing commands: 

SET RULER BOTTOM 

SET SCROLL 2 2 

SET SECTION 10 

SET HELP KEYPAD 

SET SYNTAXCHECK PROMPT 

DEFINE KEY CTRL_P_KEY REVIEW-ERROR 

See Section 3.6.8 for an example of a screen with the ruler on the bottom and the keypad 
help displayed. 


3.7.2 Startup Command Files 

Startup command files allow you to specify a set of commands to be executed automatically 
each time you begin an editing session. A startup command file can contain any of the VAX 
RPG II editor commands. It can also contain comment and blank lines to improve readabil¬ 
ity. Each command is executed as if the COMMAND function were used. 

The editor uses the COMMAND qualifier to find a startup file. This qualifier is present by 
default, with a default value of RPGINI. 

The uses of the COMMAND qualifier and their effects are: 

• If COMMAND = filespec is used, the specified file is executed. 

• If just COMMAND or if no COMMAND qualifier is used, the editor looks for the file 
RPGINI. If found, it is executed. 

• If/NOCOMMAND is used, no command file is executed. 

All startup files are opened with a default file type of RPG. The value for the COMMAND 
qualifier can be a full or partial filespec, or a logical name that translates to a filespec. 
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Control can be passed from one startup file to another by using the COMMAND option of 
the SET command. When the editor is executing commands from a startup command file 
and encounters a SET COMMAND command, it tries to find the associated file, translat¬ 
ing logical names if necessary. If a file is found, the contents of that file are then executed in 
the same way as the original startup file. The rest of the commands in the startup file are 
not executed. If the file is not found, the rest of the commands in the startup file are 
executed. 

Following are several ways of using these options to customize your editing environment. 
If you do not want to execute any startup file, your command line should look like this: 

RPG/EDIT/NOCOMMAND file-spec 

To execute your own startup commands, create a file of editor commands and define the 
logical name RPGINI to reference it. For example, if you create the file MYSTARTUP.RPG 
to contain: 

SET DEFAULT PAGE t PROMPT 
SET HELP KEYPAD 
SET RULER NONE 

DEFINE KEY CTRL_N_KEY REUIEW_ERROR 

and add to your LOGIN.COM the following: 

$ DEFINE RPGINI MYDISK:CMYDI RECTORY 3MYSTARTUP . RPG 
then, whenever you invoke the editor, your commands will be executed. 

One way to establish a customized environment for many users at once is described here. A 
system-wide startup command file can be established by defining the logical name 
RPGINI in the system logical name table. Suppose that the following file exists with the 
filename SYSRPGINI.RPG in the directory addressed by SYS$PUBLIC: 

! System-wide startup commands 
SET HELP SPECIFICATIONS 
SET RULER BOTTOM 
SET COMMAND RPGINI.RPG 

If RPGINI was defined by: 

* DEFINE/SYSTEM RPGINI SYSSPUBLIC:SYSRPGIN I . RPG 

then by default, all users on the system would have that set of commands executed auto¬ 
matically. The last command shown would mean that after executing the system-wide 
commands, the editor would also execute any commands found in the file RPGINI.RPG in 
the default directory. 
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3.7.3 Modifying Screen Length 

You can determine the number of lines on the terminal screen that are used by the RPGII 
editor. This is a useful option for a variety of reasons. If you have a terminal in the VT100 
family that does not have Advanced Video Option, you have only 14 lines when in 132 
column mode. It is also useful if you have a terminal with more than 24 lines. Also, if you 
have a terminal that runs at a slow baud rate, you can control the number of lines dis¬ 
played on the editor screen. This would improve performance over a slow communication 
line by decreasing the number of lines on the screen that must be kept updated during an 
editing session. 

Use the DCL command SET TERMINAL/PAGE = n to set the length of the page on your 
terminal screen. You can also set the width of the page with SET TERMINAL/WIDTH = n. 
If you set the width to 132 columns, you will get the full text of the editor error messages. 

Note that there must be at least six lines on the screen, to allow for the two line ruler, tab 
stop line, prompt line, message line, and one line in the source editing window. 

3.8 Creating and Editing Programs 

This section contains a sample RPG II program and some of the output it might produce. 
Section 3.8.1 shows you how to create a program using the RPG II editor, and Section 3.8.2 
shows you how to use the RPG II editor to edit a program. Both sections use the sample 
program shown here. 
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Note that this example assumes a 24-line screen and no startup file. 



H#++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 
H#— 

H 

FSHIPS IP F 41 DISK 

FSUMREP OF 98 LPRINTER 

E QTY 420 

LSUMREP 55FL 500L 
ISHIPS AA 01 
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oooooooooooooooooooooooooooo 



OSUMREP H OOi IP 

H 02 IP 

H i IP 

H 2 IP 


48 'PRODUCT SHIPMENT REPORT' 
UDATE Y 12 

48 'PRODUCT SHIPMENT REPORT' 

42 'SHIPMENTS' 

15 'DIVISION DEPT' 

24 'PRODUCT' 

48 'Qi Q2 Q3 Q4 TOTAL' 
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A sample of the output from this program might appear as follows: 

o ! 1 : 2 : 3 ! a ! 5 : e : i \ 

123456789012345678901234567890123456789012345S789012345S78901234567890123456789 
0 


9/09/85 PRODUCT SHIPMENT REPORT 

SHIPMENTS 


DIVISION 

DEPT 

PRODUCT 

0 1 

02 

03 

04 

TOTAL 




East 

12 

CPU-19 

12 

13 

14 

15 

54 






CPU-20 

1 1 

1 1 

1 1 

10 

43 





13 

TERM-12 

12 

34 

34 

35 

115 






TERM-13 

23 

24 

25 

26 

98 






TERM-20 

1 1 

12 

13 

14 

50 











3G0 

< = = Total 

for 

East 

North 

23 

DISK-45 

18 

17 

15 

14 

G4 






DISK-48 

12 

14 

20 

35 

81 






DISK-GO 

10 

10 

10 

1 1 

41 





24 

TAPE-12 

8 

7 

G 

3 

24 






TAPE-13 

1 

O 

4 

1 1 

18 






TAPE-32 

10 

10 

10 

1 1 

41 






TAPE-33 

4 

4 

4 

5 

17 











28G 

<== Total 

for 

North 

South 

25 

MEMORY-11 

19 

20 

21 

21 

81 






MEMORY-1G 

19 

18 

17 

1G 

70 






MEMORY-17 

12 

13 

13 

12 

50 











201 

<== Total 

for 

South 

West 

39 

SOFT-12 

1 1 

13 

13 

12 

49 






SOFT-14 

G 

7 

8 

8 

29 






SOFT-23 

13 

14 

20 

19 

66 





40 

SOFT-24 

15 

14 

14 

13 

5G 






SOFT-25 

3 

3 

4 

7 

17 











217 

<== Total 

for 

West 








1 >064 

<== GRAND 

TOTAL 
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3.8.1 Creating a New Program 

Invoke the RPGII editor by typing the following command: 

* RPG/EDIT MYFILE 

The RPG II editor displays the following message: 

File not f o und 


The following screen is displayed: 



0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## 

QEOB] 
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Although RPG II does not require a Control specification, it is useful to place an asterisk in 
column 7 of a Control specification to include a comment describing what your program 
does. Press either the TAB key or the RIGHT key repeatedly to move the cursor to column 
6. Enter H in column 6. Use the HELP_SPECS function (default = PF1/PF2) to display 
the specification format for the Control specification. Because the current line is a Control 
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specification, the RPGII editor automatically displays the tab stops for the Control specifi¬ 
cation. Help information will be displayed in the help window of the RPG II editor screen, 
as shown in the following example: 



Currency symbol 
I Inverted print (DIJ) 

I I Alternate collating sequence (SE) 

III IP forms position (1) 

III I 

H III I 


Oil I2I3I4I5I6I7I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


.. # 

H| 

[E0B] 
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Enter an asterisk (*) in column 7. Type the description of the program. Press the RETURN 
key at the end of each line. After the RETURN key is pressed, the RPG II editor moves the 
current line on the screen one line up, if necessary; automatically enters H in column 6; 
and moves the cursor to column 7. (Column 7 is the default setting for the SET 
STARTCOLUMN command.) To display the current default for the SET STARTCOLUMN 
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command, issue the COMMAND function (default = PF1/KP7), type SHOW 
STARTCOLUMN, and press the RETURN key, as shown in the following example: 



Currency symbol 
I Inverted print (DIJ) 

I I Alternate collating sequence (SE) 
III IP forms position (i) 

III I 

H III I 


r6 I 1 \ 2 \ 3I 4 I 5 I 6 I 7 M 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#. ........... 

H*++ 

H* FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 
H#~ 

H| 

C E0B ] 


<PF1/KP7> 


Command: SHOW STARTCOLUMN] 
STARTCOLUMN value is: 7U 
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The specification type for the current line will be duplicated until you enter a new specifi¬ 
cation type in column 6. H is automatically entered in column 6 and the cursor is moved to 
column 7. The next specification needed is the File Description specification. To replace H, 
move the cursor to column 6 by using the FIELD_BACKWARD function (default = 
BS_KEY), and enter F (File description). 

Enter the name of the file, beginning in column 7, and then use the FIELD-FORWARD 
function, hereafter referred to by its default setting, TAB_KE Y. Since help information is 
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displayed in the help window of the RPGII editor screen, once TAB_KE Y or any termina¬ 
tor is pressed, the RPG II editor displays the specification format and tab stops for the File 
Description specification, as shown in the following example: 



Mode (LR) 


I Key length 



Type (I0UD) II 

Record address type (API) 


Addtn(AU) 


IDes (PSRCTD)11 

lOrganization (IT,1-9) 


1 Expand 


IIE0F (E) II 

IIOverflow indicator 


11 Share 


IllSeci (AD) II 

1 11 Key location 


111 Rewnd 

File 

llllFmt (FV) II 

III 1 Extension (EL) 


III 1 

name 

1111IBlk Rec 11 

III 1 1 Device Symb Tape 

Core 

III IFile 

1 

IIII lien len II 

III 1 Icode dev label 

index 

III Icond 

FI 

111111 1 II 

III 1 II II 

1 

III II 


0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## ######— # — ##-### #—## # * . #-###.## .. 

H*++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 

H#— 

H 

FSHIPS | 


CE0B] 
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Remember, you can press TAB_KE Y to move the cursor to the next tab stop. Enter the rest 
of the File Description specifications as shown in the following example: 



Mode (LR) 


I Key length 
Type (IOUD) II Record address type (API) 


Addtn(AU) 



IDes (PSRCTD)11 

lOrganization (IT,1-9) 


1 Expand 


11 EOF (E) II 

IIOverflow indicator 


11 Share 


IllSecf (AD) II 

III Key location 


111 Rewnd 

File 

llllFmt (FV) II 

III 1 Extension (EL) 


III 1 

name 

IIIIIBlk Rec II 

III 1 IDevice Symb Tape 

Core 

III IFile 

1 

IIllllen len II 

III 1 Icode dev label 

index 

III Icond 

FI 

MINI 1 II 

III 1 II II 

1 

III II 

0 1 

|l23456789012 

112 1 
345678901234567890 

3 14 15 

'1234567890123456789012345678 

1 6 
9012345 

1 7 1 

678901234567890 


## ###### — # — ##-##* # — ## # - ***.** .. 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H* products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 

_ 

FSHIPS IP F 41 DISK 

FSUMREP OF 98 LPRINTER 

F| 

CE0B3 
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Replace F in column 6 with E (Extension). Press TAB_KEY. The RPGII editor displays the 
specification format and tab stops for the Extension specification. Then, enter the rest of 
the entries for the Extension specification, as shown in the following example: 



E 


From To 

file file 

name name 

I I 

I I 


111 Alternating table or array 
Table EntEnt Lenlllname Len 


or perin of Fill 
array RecTbl EntIDII 
name II I MSI 
I III INI 


of F 
EntID 
I I IS 

I 111+— Comments —+ 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# # #—#—#—#### #—#### 


H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 


H*~ 

FSHIPS 

ip 

F 

41 

DISK 

FSUMREP 

0 

F 

98 

LPRINTER 

E 

E| 



QTY 

4 2 0 


CE0B3 
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Enter L (Line Counter) in column 6. Then, enter the rest of the entries for the Line Counter 
specification, as shown in the following example: 



Form length (1-112) 

File I FL (if Form length used) 

name I I Overflow line number (1-112) 

I I I I OL (if Overflow line used) 

LI I I I I 


0111213141516171 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # - # #-# , . . . . . ..... . . . . 

H# products broken down by division and department using an 
H* input file with the shipment data for the past 4 quarters. 

41 DISK 

98 LPRINTER 

QTY 420 

500L 

CE0B1 " 


FSHIPS IP F 
FSUMREP 0 F 
E 

LSUMREP 55FL 
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Enter the Input specifications, as shown in the following example: 



Sequence (AA-ZZ, 01-99) 



1 Number (1-N) 

1 lOptional (0) 

1 II Record identifying indicator 

Decimal positions 

1 Control level 


1 III 

1 111+ Identifying codes + 

Format 

1 

1 

1 Match field 

1 1 Fid rec rel 

File 

1 III 1 1 

1 (PB) 

IField 

1 1 1 

name 

1 III 1 C C Cl 

1 Fie1d 

Iname 

1 1 1 Field 

1 

1 III 1 Z Z Zl 

1locationl1 

1 1 1 indicatrs 

II 

1 111 Pos NDcPos NDcPos NDc 

IFr To 

11 

1 1 1 + - 0 


j 0 I 1 I 2I 3 I 4 I 5 I 6 I 7 M 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### #— *— #— . ##—#-## ###### .... 


CEOBl 


E 

LSUMREP 

ISHIPS 

I 

I 

I 

I 

I| 


QTY 

55FL 500L 
AA 01 


1 5 DIV L2 

6 7 DEPT LI 

8 16 PROD 

17 24 QTY 
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Use the DISPLAY function (default = PF1/KP8) to display the program on the entire 
screen (except lines 1 through 3, 23, and 24), as shown in the following example: 



12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### #— #— *— .##—*—## a#####,.,. 

H*++ 

H* FUNCTIONAL DESCRIPTION: 


CE0B3 


H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H* input file with the shipment data for the past 4 quarters. 


H#— 
FSHIPS 

IP F 

41 

DISK 




FSUMREP 

0 F 

98 

LPRINTER 




E 

LSUMREP 

55FL 500L 

QTY 

4 2 0 




ISHIPS 

I 

AA 01 


1 

5 

DIV 

L2 

I 



6 

7 

DEPT 

LI 

I 



8 

16 

PROD 


I 



17 

24 

QTY 


II 
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Enter the Calculation specifications without displaying the specification format in the 
help window, as shown in the following example: 




c* 

c 

01 


XF00TQTY 

PROQTY 

30 

c 

01 

PROQTY 

ADD DEPQTY 

DEPQTY 

30 

c* 

CLi 


DEPQTY 

ADD DIVQTY 

DIVQTY 

30 

CLi 

CL2 


DIVQTY 

Z-ADDO 

ADD FINQTY 

DEPQTY 

FINQTY 

40 

C* 

C| 







CEOB] 
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Enter the Output specifications. Note that the RPG II editor screen can display only 19 
source lines at a time, when the terminal has 24 lines and when the ruler is displayed. 
Once you enter more than 19 lines, the RPG II editor moves the editing window up. 



0 I 11 2 I 3 I 4 I 5 1 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** 


***** * * 


***—** 


0SUMREP 

0 

H 

001 

IP 


48 

'PRODUCT SHIPMENT REPORT' 

0 

H 

02 

IP 




0 




UDATE Y 

12 


0 





48 

'PRODUCT SHIPMENT REPORT' 

0 

H 

1 

IP 




0 





42 

'SHIPMENTS' 

0 

H 

2 

IP 




0 





15 

'DIVISION DEPT' 

0 





24 

'PRODUCT' 

0 





48 

'Q1 Q2 Q3 Q4 TOTAL' 

0 

D 

1 

01 




0 




DIV 

8 


0 



LI 

DEPT 

14 


0 




PROD 

25 


0 




QTY Z 

41 


0 




PR0QTYZ 

48 


0 

T 

1 

LI 





0 | 



ZK-4366-85 


3-64 


Using the RPG II Editor 





Enter the rest of the Output specifications. Use the EXIT function (default = 
CTRL_Z_KEY) to save the contents of the editing buffer and leave the RPG II editor. 
When EXIT is used, the RPG II editor displays the following message: 

45 records written to file MYDISK:[MYDI RECTORY]MYFILE.RPG51 

This is shown in the following example: 


0 1112 13 I 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## 

##### 

# # 

# ###■ 

— ## 

0 

H 

02 

IP 




0 




UDATE Y 

12 


0 





48 

'PRODUCT SHIPMENT REPORT 

0 

H 

1 

IP 




0 





42 

'SHIPMENTS' 

0 

H 

2 

IP 




0 





15 

'DIVISION DEPT' 

0 





24 

'PRODUCT' 

0 





48 

'Q1 Q2 Q3 Q4 TOTAL' 

0 

D 

1 

01 




0 




DIV 

8 


0 



LI 

DEPT 

14 


0 




PROD 

25 


0 




QTY Z 

41 


0 




PR0QTYZ 

48 


0 

T 

1 

LI 




0 

T 

0 

LR 




0 




FINQTY1 

48 


0 





65 

'<== GRAND TOTAL' 


45 records written to file MYDISK:CMYDIRECT0RY1MYFILE.RPG; 1 
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3.8.2 Editing an Existing Program 

When you invoke the RPGII editor to edit the program created in Section 3.8.1, the RPGII 
editor displays the following message: 

45 records read from file MYDISK:CMYDI RECTORY 3MYFILE♦RPGH 

And the following screen is displayed: 



12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# ....... . 

fy H#++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 
H# products broken down by division and department using an 


H# input file with the shipment data for 

the past 4 quarters. 

H#— 

H 

FSHIPS 

IP F 

4i 

DISK 



FSUMREP 

0 F 

98 

LPRINTER 



E 

LSUMREP 

55FL 500L 

QTY 

4 2 0 



ISHIPS 

I 

AA 01 


i 

5 DIV 

L2 

I 



6 

7 DEPT 

LI 

I 



8 

16 PROD 


I 



17 

24 QTY 


C* 

C 01 


XF00TQTY 

PR0QTY 

30 


C 01 

PR0QTY 

ADD DEPQTY DEPQTY 

30 



iPress the PF2 key to get help information! 
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In this session, the control-level indicator L2 needs to condition the DIV field in the detail 
record Output specification. Use the FIND function (default = PF1/PF3) to locate DIV. 
The RPG II editor displays the command prompt “Search for: ”. Enter the search string 
DIV and press the ENTER key, as shown in the following example: 



0 I 1 I 2I 3 I V I5I 6 1 7 M 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# . #. ., .# . * 


H*++ 

H* FUNCTIONAL DESCRIPTION: 


H* 

H# 

H# 

H#— 

H 

FSHIPS 

FSUMREP 

E 

LSUMREP 

ISHIPS 

I 

I 

I 

I 

C* 

C 
C 


This program produces a report of shipments for various 
products broken down by division and department using an 
input file with the shipment data for the past 4 quarters. 


01 

01 


IP 

0 


41 

98 

QTY 


55FL 500L 
AA 01 


DISK 

LPRINTER 
4 2 0 


1 

6 

8 

17 


PR0QTY 


XF00TQTY 
ADD DEPQTY 


5 DIV 
7 DEPT 
16 PROD 
24 QTY 


L2 

LI 


PR0QTY 

DEPQTY 


30 

30 


Search for: DIV 
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The RPG II editor responds by moving the cursor to the first character of the first occur¬ 
rence of the search string DIV (see the comment line), as shown in the following example: 



0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
SSfegMl23456789012345678901234567890123456789Q12345678901234567890123456789Q1234567890 


........ 

H#++ 

H# FUNCTIONAL DESCRIPTION: 

H# This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 


H#— 

H 

FSHIPS 

IP F 

41 

DISK 


FSUMREP 

0 F 

98 

LPRINTER 


E 

LSUMREP 

55FL 500L 

QTY 

4 2 0 


ISHIPS 

I 

AA 01 


1 

5 DIV 

I 



6 

7 DEPT 

I 



8 

16 PROD 

I 



17 

24 QTY 

C* 

C 01 


XF00TQTY 

PROQTY 

30 

C Oi 

PROQTY 

ADD DEPQTY 

DEPQTY 

30 
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Because this is not the correct string, use the FIND_NEXT function (default = PF3). The 
RPG II editor moves the cursor to the first character of the next occurrence of the string 
DIV, as shown in the following example: 



12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### #— #— #— .##—*—## ###### .... 

H*++ 


H# FUNCTIONAL DESCRIPTION: 


H* This program produces a report of shipments for various 

H# products broken down by division and department using an 

H# input file with the shipment data for the past 4 quarters. 


H*~ 

H 

FSHIPS IP F 41 

FSUMREP OF 98 

E QTY 

LSUMREP 55FL 500L 
ISHIPS AA 01 
I 
I 
I 
I 


DISK 

LPRINTER 
4 2 0 


1 5 0IV L2 

6 7 DEPT LI 

8 16 PROD 
17 24 QTY 


C* 


C 01 XF00TQTY PR0QTY 30 

C 01 PR0QTY ADD DEPQTY DEPQTY 30 
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Again, this occurrence of the string DIV is not correct, so issue the FIND_NEXT function 
five more times to move the cursor to the correct occurrence. You could have specified DIV 
and a blank as the search string to avoid duplicating key strokes. L2 must be entered in 
columns 24 and 25. To do this, move the cursor to column 24 by pressing the BS_KEY to 
column 23, then use the RIGHT function (default = RIGHT) once. Enter the string L2 in 
columns 24 and 25, as shown in the following example: 



0I1I2I3I4I5I6I7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## 

##### # # 

* 

###- 



C 01 

c* 

PR0QTY 

ADD 

DEPQTY 

DEPQTY 

30 

CL1 

CL1 

DEPQTY 

ADD DIVQTY 
Z-ADD0 

DIVQTY 

DEPQTY 

30 

CL2 

DIVQTY 

ADD 

FINQTY 

FINQTY 

40 


C# 

0SUMREP H 001 IP 


W W W 1 II \ l_ 1 

0 




48 

'PRODUCT SHIPMENT REPORT 

0 

H 02 

IP 




0 



UDATE Y 

12 


0 




48 

'PRODUCT SHIPMENT REPORT 

0 

H 1 

IP 




0 




42 

'SHIPMENTS' 

0 

H 2 

IP 




0 




15 

'DIVISION DEPT' 

0 




24 

'PRODUCT' 

0 




48 

'Qi Q2 Q3 Q4 TOTAL' 

0 

D 1 

01 




0 


L2| 

DIV 

8 
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Number the program lines for reference by issuing the COMMAND function (default = 
PF1/KP7) and typing the RESEQUENCE command, as shown in the following example: 



0 111 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** 

***** * * 

* 

***- 

—** 


190C 01 

2000 

PROQTY 

ADD 

DEPQTY 

DEPQTY 

30 

210CL1 

220CL1 

DEPQTY 

ADD DIVQTY 
Z-ADDO 

DIVQTY 

DEPQTY 

30 

230CL2 

DIVQTY 

ADD 

FINQTY 

FINQTY 

40 


2400 


2500SUMREP 

2600 

H 

001 

IP 


48 

'PRODUCT SHIPMENT REPORT' 

2700 

H 

02 

IP 




2800 




UDATE Y 

12 


2900 





48 

'PRODUCT SHIPMENT REPORT' 

3000 

H 

1 

IP 




3100 





42 

'SHIPMENTS' 

3200 

H 

2 

IP 




3300 





15 

'DIVISION DEPT' 

3400 





24 

'PRODUCT' 

3500 





48 

'Q1 Q2 Q3 Q4 TOTAL' 

3600 

D 

1 

01 




3700 



L2tt 

DIV 

8 



Command: RESEQUENCE 
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Use the SECTION function (default = KP8) to move the cursor the number of lines set by 
the SET SECTION command, as shown in the following example: 



j 0 I 1I 2I 3 1 4 1 5 I 6 I 7 ll 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## ##### # # # ###—## 


2800 




UDATE Y 

12 


2900 





48 

'PRODUCT SHIPMENT REPORT 

3000 

H 

1 

IP 




3100 





42 

'SHIPMENTS' 

3200 

H 

2 

IP 




3300 





15 

'DIVISION DEPT' 

3400 





24 

'PRODUCT' 

3500 





48 

'Q1 Q2 Q3 Q4 TOTAL' 

3600 

D 

1 

01 




3700 



L2 

DIV 

8 


3800 



Ll 

DEPT 

14 


3900 




PROD 

25 


4000 




QTY Z 

41 


4100 




PR0QTYZ 

48 


4200 

T 

1 

Ll 




4300 

T 

0 

LR 




4400 




FINQTY1 

48 


4500 



1 


65 

'<== GRAND TOTAL' 


CE0B] 
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Enter two Output specifications between lines 420 and 430 by using the following 
functions: 

1. UP (default = UP) to line 430 

2. OPEN_LINE (default = PF1/KP0) to create a new line 

Use the OPEN_LINE function to create a line preceding the current line. The RPGII edi¬ 
tor automatically places the specification type of the current line in column 6 and moves 
the cursor to column 7. Enter the new specifications, as shown in the following example: 



12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## 

##### 

* * 

# 

###• 

—## 

2900 






48 'PRODUCT SHIPMENT REPORT 

3000 

H 

1 

IP 




3100 






42 'SHIPMENTS' 

3200 

H 

2 

IP 




3300 






15 'DIVISION DEPT' 

3400 






24 'PRODUCT' 

3500 






48 'Qi Q2 Q3 Q4 TOTAL' 

3600 

D 

1 

01 




3700 



L2 

DIV 


8 

3800 



LI 

DEPT 


14 

3900 




PROD 


25 

4000 




QTY 

Z 

41 

4100 




PR0QTYZ 

48 

4200 

T 

1 

LI 




0 

T 

0 

L2 




0 




DIV 


69| 

4300 

T 

0 

LR 



4400 




FINQTY1 

48 

4500 






65 '<== GRAND TOTAL' 
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Enter another two specifications (identical to the two specifications just entered), by using 
the following functions: 

1. SELECT (default = PERIOD) to mark the beginning of the selected region 

2. UP (default = UP) once 

3. CUT (default = KP6) to place the selected region into the paste buffer 

4. PASTE (default = PF1/KP6) twice 

The following example shows the effects of the procedure described above: 



12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## 

##### 

# # 

# 

*«*- 


2900 






48 'PRODUCT SHIPMENT REPORT 

3000 

H 

1 

IP 




3100 






42 'SHIPMENTS' 

3200 

H 

2 

IP 




3300 






15 'DIVISION DEPT' 

3400 






24 'PRODUCT' 

3500 






48 'Qi Q2 Q3 Q4 TOTAL' 

3600 

D 

1 

01 




3700 



L2 

DIV 


8 

3800 



LI 

DEPT 


14 

3900 




PROD 


25 

4000 




QTY 

z 

41 

4100 




PRQQTYZ 

48 

4200 

T 

1 

LI 




0 

T 

0 

L2 




0 




DIV 


69 

0 

T 

0 

L2 




0 




DIV 


69 

4300 

T 

0 

LR 



1 
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Enter another four specifications. Then, remove the line numbers, as shown in the follow¬ 
ing example: 



j 0 I 1I 2I 3 I 4 I 5 I 6 I 7 M 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## ##### * # # ##*—## 


0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


ICommand: RESEQUENCE/REMOVEI 



15 

'DIVISION DEPT 


24 

'PRODUCT' 


48 

'Qi Q2 Q3 Q4 

DIV 

8 


DEPT 

14 


PROD 

25 


QTY Z 

41 


PR0QTYZ 

48 



DIV 

69 

DIV 

69 

DIVQTYZB 

48 


63 '<== Total for' 

DIV 

69| 


H 2 IP 


D 1 01 

L2 
Li 


T 1 Li 

TO L2 

TO L2 

T 02 L2 


TOTAL' 
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Use the COMMAND function and type the EXIT command to save the modified program, 
as shown in the following example: 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


Qi Q2 Q3 Q4 TOTAL' 


** 

***** 

* * 

* 

***■ 

-—** 

0 

H 

2 

IP 




0 






15 '] 

0 






24 '1 

0 






48 '! 

0 

D 

1 

01 




0 



L2 

DIV 


8 

0 



LI 

DEPT 


14 

0 




PROD 


25 

0 




QTY 

z 

41 

0 




PR0QTYZ 

48 

0 

T 

1 

LI 




0 

T 

0 

L2 




0 




DIV 


69 

0 

T 

0 

L2 




0 




DIV 


69 

0 

T 

02 

L2 




0 




DIVQTYZB 

48 

0 






63 ' 

0 




DIV 


691 


Command: EXIT 

53 records written to file MYDISK:CMYDIRECTORYIMYFILE.RPG;2 
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Chapter 4 

Using Indicators 


Indicators are two-character alphabetic, numeric, or alphanumeric entries that condition 
the steps of a program cycle. 

Each indicator has a specific function; however, some indicators can be used for more than 
one purpose. Generally, you use indicators to control the following program decisions: 

• Under what conditions RPGII uses a file during program execution 

• When and under what conditions RPG II performs calculations 

• When RPG II can access a field for input 

• Under what conditions RPG II writes a field or record to an output file 

To use an indicator to control program operations, you first define the conditions under 
which it is set on or off. Then, you check the status (on or off) of the indicator to determine 
what steps your program should perform. 

This chapter discusses types of indicators and explains how to use them. 

4.1 User Defined Indicators 

You can define certain groups of indicators in your program; others are defined internally. 
Sections 4.1 through 4.1.5 discuss those indicators you can define. Section 4.2 describes 
internally defined indicators. 

4.1.1 Record-Identifying Indicators 

Record-identifying indicators, as their name implies, identify record types. Define each 
record type by specifying an identification code in columns 21 through 41 of the Input spec¬ 
ification. Then, associate an indicator in columns 19 and 20 with that record type. 

In the following example, RPG II associates the record-identifying indicator 01 with a 
record type. 


4-1 



Sequence (AA-ZZ, 01-99) 



1 

Number (1-N) 





1 

lOptional (0) 

Decimal positions 


1 

II Record identifying indicator 

1 

Control level 


1 

111 

1 

1 

Match/chain field 


1 

111+ Identifying codes + Format 

1 

1 

1 Field rec rel 

File 

1 

III 1 II 

IField 

1 

1 1 

name 

1 

III 1 C C Cl IField 

Iname 

1 

1 1 Field 

1 

1 

III 1 Z Z Zl 1locationl1 

1 

1 1 indicators 

II 

1 

III Pos NDcPos NDcPos NDc IFr To 

11 

1 

1 1 + - 0 

0 1 

1 

1 2 1 3 1 4 1 

5 


1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

# 

### #— #— #— . #*—#— 

-## 

* 

#####.... 

IINPUT 

AA 

01 20 Cl 
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In this example, if the character in the twentieth position is the number 1, the indicator 01 
is set on. Then, you can use the indicator to condition operations for that particular record 
type. 

You can use any of the following indicators as record-identifying indicators: 

• 01 through 99 

• LI through L9 

• LR 

• HI through H9 

By assigning a different record-identifying indicator for each record type in a file, you can 
condition calculation and output operations for specific record types. 

The record-identifying indicator for a particular record type is set on when RPG II 
processes a record of that type. For a primary or secondary file, the record-identifying indi¬ 
cator is set on before total-time calculations. For a chained or demand file, the record-iden¬ 
tifying indicator is set on immediately after the record is read. In either case, it is set off 
when the program reaches the end of the current program cycle (after detail-time output). 


4—2 Using Indicators 









You can use record-identifying indicators to condition both detail-time and total-time 
operations in that cycle and indicate which operation(s) to perform for each record type. 
The following example shows how record-identifying indicators can be used to condition 
program operations: 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


li 

ISALES 

AA 

01 

1 CJ 




12 

I 







2 

50ITEM 

13 

I 







10 

16 DESCR 

14 

I 







20 

242SALES 

15 

I 







30 

342C0ST 

16 

I 







40 

432PR0FIT 

17 

c 

01 


SALES 


SUB 

COST 

NET 

52 

18 

c 

01 


TSALES 

ADD 

SALES 

TSALES 

62 

19 

c 

01 


TC0ST 


ADD 

COST 

TC0ST 

62 

20 

c 



TPR0FI 

ADD 

NET 

TPR0FI 

62 

21 

0REP0RT 

H 

201 

IP 





22 

0 


OR 


OF 





23 

0 






UDATE Y 

8 


24 

0 







44 7 JANUARY SALES REPORT 

25 

0 






PAGE 

72 


26 

0 







68 'PAGE 

/ 

27 

0 


H 

22 

IP 





28 

0 


OR 


OF 





29 

0 







5 'ITEM 

T 

30 

0 







23 'DESCRIPTION' 

31 

0 







41 'SALES' 

32 

0 







56 'COST 

r 

33 

0 







72 'PROFIT' 

34 

0 


D 


01 





35 

0 






ITEM 3 

5 


36 

0 






DESCR 

25 


37 

0 






SALES 1 

41 


38 

0 






COST 1 

57 


39 

0 






PR0FIT1 

72 


40 

0 


T 

1 

LR 





41 

0 







30 'TOTALS' 

42 

0 






TSALES1 

41 '$' 


43 

0 






TC0ST 1 

57 '$' 


44 

0 






TPR0FI1 

72 '$' 
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In this example: 

• Line 11 causes RPG II to begin reading records from the file SALES. The identifica¬ 
tion code (columns 21 through 41) groups these records according to a code that repre¬ 
sents the month. If the code for the month is J, the record-identifying indicator 01 is 
set on. 
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• Lines 17 through 19 use the same record-identifying indicator 01 to condition detail¬ 
time calculations. RPG II performs the calculation each time a record is read of the 
type described on line 11. 

• Line 34 uses the same record-identifying indicator to condition detail-time output. 
RPG II performs the output operation each time a record is read of the type described 
on line 11. 

The output file produced by this program might appear as follows: 


o ! i i 2 : 3 ! a i 5 : e : 7 i 

1234567890123456789012345678901234567890123456783012345678901234567890123456783C 


2/4/83 

JANUARY 

SALES REPORT 


ITEM 

DESCRIPTION 

SALES 

COST 

10005 

AMMONIA 

60 ♦ 30 

50 ♦ 00 

10982 

MATCHES 

295 * 00 

205♦00 

22650 

NUTMEG 

209♦00 

170* 00 

TOTALS 

$564*30 $425 

♦ 00 $139*30 



PAGE 1 

PROFIT 

1 0 ♦ 30 
90 ♦ 00 
39 ♦ 00 


If you use the CHAIN or READ operation to retrieve records, the program does not set the 
record-identifying indicators off until the beginning of the next program cycle. Be careful 
when performing more than one CHAIN or READ operation for a file with multiple record 
types, because more than one indicator can be set on during a single cycle. 

4.1.2 Field Indicators 

Field indicators test a field in an input record for a positive, negative, zero, or blank value. 
The following lists ways to test for these values: 

• For a positive value, specify a field indicator in columns 65 and 66 of the Input 
specification. 

• For a negative value, specify a field indicator in columns 67 and 68 of the Input 
specification. 

• For a zero or blank value, specify a field indicator in columns 69 and 70 of the Input 
specification. 

You can use any of the following indicators as field indicators: 

• 01 through 99 

• HI through H9 


4-4 Using Indicators 



Field indicators are set when the data in the field is extracted from the record. Once a field 
indicator is set, it remains set until the next time the field is extracted, unless it is set off by 
another use of the same indicator in the program. A field indicator can be used to condition 
any detail-time or total-time operations. However, at total time, the field indicators 
assigned to fields from a primary or secondary file retain the setting from the previous 
detail-time cycle. 

The following example shows how field indicators can be used to condition a calculation: 


0 I 1 I 2 I 3 I 4-1 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


24 IPARTLIS AA 01 

1 CF 



25 I 


2 100INVCDE 

112233 


41 

C 

11 

ITEM 

MULT FACT1 

ORDER 

62H 

42 

C 

22 

ITEM 

MULT FACT2 

ORDER 

62H 

43 

C 

33 

ITEM 

MULT FACT3 

ORDER 

62H 
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In the above example: 

• Line 25 tests the value of the field INVCDE to see if it contains a positive value, a 
negative value, or a zero value. The following lists which indicator is set on for each 
value: 

- If the field contains a positive value, indicator 11 is set on and indicators 22 and 33 
are set off. 

- If the field contains a negative value, indicator 22 is set on and indicators 11 and 33 
are set off. 

- If the field contains a zero value, indicator 33 is set on and indicators 11 and 22 are 
set off. 

• Lines 41 through 43 calculate the number of parts to order according to the status of 
the field indicators. 
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4.1.3 Resulting Indicators 

Resulting indicators condition operations that depend on the result of a calculation. These 
indicators specify the test (>, <, or =) and indicate the result of the calculation. If the 
result matches the test, the indicators are set on. The following lists when these indicators 
are set off: 

• The next time the calculation is performed and the result of the calculation does not 
satisfy the test the indicator specifies 

• By another use of the same indicator in the program 

You specify resulting indicators in columns 54 through 59 of the Calculation specification. 
You can use any of the following indicators as resulting indicators: 

• 01 through 99 

• LI through L9 

• LR 

• HI through H9 

• OA through OG, and OV 

• U1-U8 

• KA through KZ 

• K0 through K9 

Resulting indicators in columns 54 and 55 test for the following conditions: 

• The Result field contains a positive value after an arithmetic operation. 

• The value in Factor 1 is higher than the value in Factor 2 in a COMP operation. 

• The value of the element found in Factor 2 is higher than the value in Factor 1 in a 
LOKUP operation. 

• The record is not found in a CHAIN operation. 

• Each bit defined in Factor 2 is off in the Result field for a TESTB operation. 
Resulting indicators in columns 56 and 57 test for the following conditions: 

• The Result field contains a negative value after an arithmetic operation. 

• The value in Factor 1 is lower than the value in Factor 2 in a COMP operation. 

• The value of the element found in Factor 2 is lower than the value in Factor 1 in a 
LOKUP operation. 
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• The defined bits in Factor 2 are of mixed status (some on, some off) in the Result field 
for a TESTB operation. 

• A subprogram returns with an error status from a CALL operation. 

Resulting indicators in columns 58 and 59 test for the following conditions: 

• The Result field contains a zero after an arithmetic operation. 

• The value in Factor 1 is equal to the value in Factor 2 in a COMP operation. 

• The value of the element found in Factor 2 is equal to the value in Factor 1 in a 
LOKUP operation. 

• An end-of-file condition occurs for the demand file in a READ operation. 

• Each bit defined in Factor 2 is on in the Result field for a TESTB operation. 

Resulting indicators are also used with the SETON and SETOF operation codes to specify 
that the indicator(s) be set on or off. 

The following example shows how resulting indicators can be used to control program 
operations: 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

II NxxNxxNxxl 

1 1 

1 1 

!!><=+- Comments — 


I 0 i I I 2I 3 I 4I 5 i 6 I 7n 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** # 

# 

# # 

# 

#--### # # 

10 C 

SEARCH 

LOKUPTABi 


10 ii 

20 C 

FLDi 

COMP 100 


222324 

30 C 

KEY 

CHAINFILEi 


32 

40 C 


TESTB'123' 

TEST 

404142 

50 C 


READ FILEi 


50 

60 C 


SETOF 


iOii 

70 C 

FLDi 

SUB FLD2 

RES 

606162 
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In the above example: 

• Line 10 causes RPGII to search for the field SEARCH in the table TAB1. If RPGII can 
find an entry that is equal to the search word, indicator 11 is set on. If RPG II can find 
an entry that is nearest to and higher in sequence than the search word, indicator 10 
is set on. 
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• Line 20 causes RPG II to compare the contents of the field FLD1 with the numeric 

literal 100. If the contents of FLD1 are greater than 100, indicator 22 is set on and 
indicators 23 and 24 are set off. If the contents of FLD1 are less than 100, indicator 23 
ic cof rm Qinrl irir[i99 cirirl 9 A nra caf off Tf the COH^eiltS of FLD1 1QO iinrl ina- 

tor 24 is set on and indicators 22 and 23 are set off. 

• Because the input file is an indexed file, line 30 tells RPG II to retrieve a record using 
the key KEY from the indexed file FILE1. If the record is not found, indicator 32 is set 
on. Otherwise, indicator 32 is set off. 

• Line 40 causes RPG II to test the bits 1,2, and 3 in the field TEST. If the bits are all off, 
indicator 40 is set on and indicators 41 and 42 are set off. If some bits are on and some 
are off, indicator 41 is set on and indicators 40 and 42 are set off. If the bits are all on, 
indicator 42 is set on and indicators 40 and 41 are set off. 

• Line 50 causes RPG II to read the next record from FILE1. If an end-of-file condition 
occurs, indicator 50 is set on. Otherwise, indicator 50 is set off. 

• Line 60 sets indicators 10 and 11 off. 

• Line 70 causes RPG II to evaluate the contents of the Result field after the SUB opera¬ 
tion. If the Result field contains a positive value, indicator 60 is set on and indicators 

61 and 62 are set off. If the Result field contains a negative value, indicator 61 is set on 
and indicators 60 and 62 are set off. If the Result field contains a zero value, indicator 

62 is set on and indicators 60 and 61 are set off. 

4.1.4 Control-Level Indicators 

You use control-level indicators to indicate that a particular field in the input record is a 
control field. Each time RPG II reads a record that contains the control field, it compares 
the data in the control field with the current value of the control field. If the contents 
change, a control break occurs, the control-level indicator is set on, and the value in the 
control field becomes the new current value. 

You associate a control-level indicator with an input field by specifying the indicator in 
columns 59 and 60 of the Input specification. 

You can use L9, L8, L7, L6, L5, L4, L3, L2, and LI as control-level indicators. The lowest 
control level is LI and the highest is L9. When you use more than one control-level indica¬ 
tor and a higher level control-level indicator is set on because of a control break, RPG II 
automatically sets on all lower level control-level indicators. When you use a control-level 
indicator as another type of indicator (for example, as a record-identifying indicator), and 
that indicator is set on, lower level control-level indicators are not automatically set on. 
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A control break is likely to occur after the first record with a control field is read. RPG II 
compares the data in the control field with hexadecimal zeros. Therefore, RPG II bypasses 
total-time calculation and output operations for the first record containing control fields. 

All control-level indicators are set on before total-time calculations when the LR (last- 
record) indicator is on. All control-level indicators are set off after detail-time output. 

The following example shows how to use three different control-level indicators to condi¬ 
tion calculation and output operations. 
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0111213141516171 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


1 H 

2 FSLSCAR IP F 14 DISK 


3 FSLSREP 0 F 132 OF 

A TCl cr AD AA AJ 

■ 1WL.UUMH nn Vi 

5 I 

6 I 

7 I 

8 I 


9 

C 01 


SLSAMT 

ADD 

CUSTOT 

10 

CL1 


CUSTOT 

ADD 

SPTOT 

11 

CL2 


SPTOT 


ADD 

BRTOT 

12 

CL3 


BRTOT 


ADD 

FINTOT 

13 

OSLSREP 

H 

201 

IP 



14 

0 

OR 


OF 



15 

0 





UDATE Y 

16 

0 






17 

0 






18 

0 





PAGE 

19 

0 

H 

1 

IP 



20 

0 

OR 


OF 



21 

0 






22 

0 






23 

0 






24 

0 






25 

0 

H 

2 

IP 



26 

0 

OR 


OF 



27 

0 






28 

0 






29 

0 






30 

0 






31 

0 

D 

1 

01 



32 

0 





BRANCHZ 

33 

0 





SLSPERZ 

34 

0 





CUSTNOZ 

35 

0 





SLSAMT1 

36 

0 

T 

2 

LI 



37 

0 





CUST0T1B 

38 

0 






39 

0 

T 

12 

L2 



40 

0 






41 

0 





SLSPERZ 

42 

0 





SPTOT IB 

43 

0 






44 

0 

T 

3 

L3 



45 

0 






46 

0 





BRANCHZ 

47 

0 





BRTOT IB 

48 

0 






49 

0 

T 

1 

LR 



50 

0 






51 

0 





FINT0T1 

52 

0 
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PRINTERTMP 

1 20BRANCHL3 
3 40SLSPERL2 
5 90CUSTN0L1 
10 142SLSAMT 
CUSTOT 62 
SPTOT 72 
BRTOT 72 
FINT0T 82 


9 

25 'SALES REPORT' 
38 'PAGE' 

43 


6 'BRANCH' 

22 'SALESPERSON' 
35 'CUSTOMER' 

46 'SALES' 


4 'NO' 

19 'NO' 

32 'NO' 

46 'AMOUNT' 

4 

16 

30 

45 

45 

46 '*' 

42 'TOTAL SALESPERSON' 

45 
54 

56 '##' 

46 'TOTAL BRANCH NO' 

49 

61 

65 '###' 

46 'FINAL TOTAL' 

59 '$' 

64 '####' 
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In this example: 

• Lines 5 through 7 assign three control-level indicators, one each to three different 
control fields. The specification associates the highest control-level indicator (L3) to 
the most significant input field BRANCH. The specification associates the next high¬ 
est control-level indicator to SLSPER and the lowest control-level indicator to 
CUSTNO. 

If the value of BRANCH changes from the previous record, indicator L3 is set on. 
Also, when indicator L3 is set on, indicators L2 and LI are automatically set on. These 
three indicators can be used to condition calculation and output operations. 

• In line 10, when indicator LI is on, RPGII adds the amount of the customer sale to the 
total sales for a particular salesperson. In line 11, when indicator L2 is on, RPG II 
adds the total sales for the salesperson to the total sales for each branch. In line 12 
when indicator L3 is on, RPG II adds the total sales for each branch to compute the 
final total. 

• Line 36 causes RPG II to output the total sales for each customer number when LI is 
on. 

• Line 39 causes RPG II to output the total sales for each salesperson when L2 is on. 

• Line 44 causes RPG II to output total sales for each branch when L3 is on. 

You can assign the same control-level indicator to more than one control field. These fields 
are called split-control fields. The following example shows how to use split-control fields: 


Sequence (AA-ZZ, 01-99) 



1 Number (i-N) 

1 lOptional (0) 

1 IIRecord identifying indicator 

Decimal positions 

1 Control level 


1 III 

1111+ Identifying codes + 

Format 

1 

1 

1 

1 

Match field 

1 Fid rec rel 

File 

1 III 1 1 

1 <PB) 

1 Fie 1 d 

1 

1 1 

name 

1 III 1 C C Cl 

1 Fie 1d 

Iname 

1 

1 1 Field 

1 

1 III 1 Z Z Zl 

1locationl1 

1 

1 1 indicatrs 

II 

1 III Pos NDcPos NDcPos NDc 

IFr To 

II 

1 

1 1 + - 0 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** # ### *— # — # — , **— # — #* ######,.,. 


5 I 1 20BRANCHL1 

6 I 3 40SLSPERL1 

7 I 5 90CUSTN0L1 
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In this example, the fields BRANCH, SLSPER, and CUSTNO combine to form the control 
field. When RPG II compares the data in these fields with the same fields in a previous 
record, indicator LI is set on when the data changes. 
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4.1.5 Overflow Indicators 


When the printer reaches the overflow line that signals the end of the page, RPGII sets on 
the overflow indicator assigned to that printer output file. 

You can use OA, OB, OC, OD, OE, OF, OG, and OV as overflow indicators. Define overflow 
indicators in columns 33 and 34 of the File Description specification. 

In the following example, after reaching the overflow line, RPG II sets on the overflow indi¬ 
cator OF. Then, the printer moves to the top of the next page and outputs the heading lines. 



Type (HDTE) 

Edit codes 

r 

0 

No 

CR 

- 


1 Fetch overflow (F) 

1 X 

- 

— 

--- 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


111 Skip 

1 Z zero suppress 

Y 

N 

2 

B 



III 1 

1 

N 

Y 

3 

C 

L 

File 

name 

i 

III 1 Indicators 

III 1 1 Field 

111 1 1 name 

111 1 1 1 

1 Blank-after (B) 

IIEnd position 

III Format (PB) 

in i 

N 

N 

4 

D 

M 

01 

11 BAB A NxxNxxNxxl 

in i 

III 1+ Constant 

or i 

edit 

word 

+ 

0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 

1123456789012345678901234567890123456789012345678901234567890123456789012345678901 


## ##### # # # ###—## 

14 OSLSREP H 201 OF 

15 0 UDATE Y 9 

16 0 

17 0 

18 0 PAGE 


25 'SALES REPORT' 
38 'PAGE' 

43 
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See Part I, Chapter 6 for a full description of the overflow routine and overflow indicators. 


4.1.6 K Indicators 

K indicators can be used to condition calculations, output records and output fields. They 
can also be used as resulting indicators. 
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In the following program, the K indicator turned on is displayed when its associated cursor 
control key is typed. CTRL/Z is typed to end the program. 



F#+ 

F# File: READ-CURSOR.RPG 
F# 

F* This RPG II program demonstrates the use of the RTL routine 
F# SMG$READ_KEYSTROKE to read a keystroke from the terminal. 

F# 

F# The program takes input from the terminal until CTRL/Z is typed. 
F# If any of the four cursor positioning keys is typed, a string 
F# is displayed corresponding to the key. 

F# 

F# Build this program using the following commands: 

F# 

F# ♦ RPG READ-CURSOR 
F# $ CREATE SMGDEF.MAR 

F# .TITLE SMGDEF - Define SMG$ constants 

F* .Ident /i-000/ 

F# ISMGDEF GLOBAL 

F# .END 

F* $ MACRO SMGDEF 

F* $ LINK READ-CURSOR,SMGDEF 

F#~ 

FTTY D V 5 TTY 

C CALL REAKEY 

C# External definitions for SMG routines. 


c 



CREKB 

EXTRN'SMG$CREATE_VIRTUAL_KEYBOARD' 

c 



DELKB 

EXTRN'SMG$DELETE_VIRTUAL_KEYBOARD' 

c 



REAKEY 

EXTRN'SMG$READ_KEYSTROKE' 


c# 

External definitions for SMG terminators. 


c 



T_UP 

EXTRN'SMG$K_TRM_UP' 


c 



T-DOUN 

EXTRN'SMG$K_TRM_DOWN' 


c 



T.LEFT 

EXTRN'SMG$K_TRM_LEFT' 


c 



T.RIGHT 

EXTRN'SMG$K_TRM_RIGHT' 


c 



T-CTRLZ 

EXTRN'SMG$K_TRM_CTRLZ' 


c* 

Create 

the virtual 

keyboard. 


c 

N99 



CALL CREKB 


c 




PARM KB_ID 90 WL 


c 




SETON 99 


c# 

Read 

a 

keystroke. 



c 




CALL REAKEY 


c 




PARM KB_ID 90 RL 


c 




PARM T.CODE 50 UU 


c# 

Turn 

on 

an indicator if a cursor positioning key was typed. 

c 



T.CODE 

COMP T_UP 

KA 

c 



T-CODE 

COMP T.DOUN 

KB 

c 



T.CODE 

COMP T.LEFT 

KC 

c 



T.CODE 

COMP T.RIGHT 

KD 

c# 

Turn 

on 

LR to cjuit 

if CTRL/Z was typed. 


c 



T-CODE 

COMP T-CTRLZ 

LR 

c* 

Display 

a message 

if a cursor positioning key was typed. 

c 

KA 


'UP' 

DSPLYTTY 


c 

LB 


'DOWN' 

DSPLYTTY 


c 

KC 


'LEFT' 

DSPLYTTY 


c 

KD 


'RIGHT' 

DSPLYTTY 


c* 

Delete 

the virtual 

keyboard. 


CLR 



CALL DELKB 


CLR 



PARM KB_ID 90 RL 
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4.2 Internally Defined Indicators 

There are some indicators that you need not define; RPGII defines them for you. This sec¬ 
tion describes internally defined indicators and explains hnw to use them 

4.2.1 First-Page Indicator 

When you specify a first-page (IP) indicator, it is set on at the start of the program and set 
off after detail-time output but before the first record is read. Therefore, you can use the IP 
indicator to condition those heading lines you want printed before RPG II processes the 
first record. 

You specify the IP indicator, which is always represented by IP, in columns 24 and 25, 27 
and 28, or 30 and 31 of the Output specification. 

The following example shows how to use the IP indicator to print a header on the first page 
of a report: 



Type (HDTE) 

Edit codes 

/ 

0 

No CK 

- 


1 Fetch overflow (F) 

1 X 

— 

— 


— 


11 Space 

1 Y date edit 

Y 

Y 

i A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 B 

k: 


in i 

1 

N 

Y 

3 C 

L 

File 

name 

i 

III 1 Indicators 

INI 1 Field 

111 1 1 name 

I Blank-after (B) 

II End position 

III Format (PB) 

III 1 

III 1+ Constant 

N 

N 

4 D 

M 

01 

11 1 1 1 1 

1IBAB A NxxNxxNxxl 

or i 

edit 

word 

+ 

10 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

Ii234567890i2345678901234567890i23456789012345678901234567890i234567890i234567890| 


## 

##### # 

# 

# 

###—## 

• ■«■ 

00UTPUT 

H 201 

IP 





0 

OR 

OF 





0 



UDATE 

Y 8 



0 




43 

'SALES REPORT' 


0 



PAGE 

72 



0 




67 

'PAGE' 


0 

H 22 

IP 





0 

OR 

OF 





0 




5 

'ITEM' 


0 




23 

'DESCRIPTION' 


0 




41 

'SALES' 


0 




56 

'COST' 


0 




72 

'PROFIT' 
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The following heading lines are printed on the first page: 


O ! 1 ! 2 i 3 ! 4 ! 5 ! 6 ! 7 ! 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

5/19/83 SALES REPORT PAGE 1 

ITEM DESCRIPTION SALES COST PROFIT 


You can use the IP indicator to condition only detail or heading output lines. If you have a 
detail or heading output line conditioned by no indicators or all negative indicators, use a 
negative IP (NIP) indicator to prevent this line from being output on the first cycle before 
the first record is read. 


4.2.2 Last-Record Indicator 

Like the first cycle in an RPG II program, the last cycle differs from all other program 
cycles. Once RPG II processes the last record in all primary and secondary files for which 
you specified processing until the end-of-file, the last-record (LR) indicator is set, along 
with all the other control-level indicators you specified. The LR indicator causes RPG II to 
perform all total-time calculation and output operations conditioned by any control-level 
indicators and by the LR indicator. 

The LR indicator is always represented by LR, as shown in the following example: 



Type (HDTE) 

Edit codes 

/ 

0 

No CR 

- 


1 Fetch overflow (F) 

1 X 

— 

— 


— 


1 1 Space 

1 Y date edit 

Y 

Y 

1 A 

J 


III Skip 

III 1 

1 Z zero suppress 

Y 

N 

2 B 

K 


1 

N 

Y 

3 C 

L 

File 

name 

i 

III 1 Indicators 

III 1 1 Field 

111 1 1 name 

1 11 1 1 1 

I Blank-after (B) 

II End position 

III Format (PB) 
III 1 

III 1+ Constant 

N 

N 

4 D 

M 

01 

1IBAB A NxxNxxNxxl 

or edit 

word 

+ 

0 1112 13 14 15 16 17 1 

|l234567890123456789012345678901234567890i234567890123456789012345678901234567890| 


## 

###*# * # 

# ###- 

-—## 

■ • ■ ■ 

0 

T i LR 




0 



30 'TOTALS' 


0 


TSALESi 

41 '$' 


0 


TCOST i 

57 '$' 


0 


TPROFIi 

72 '$' 
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The following information is printed only after processing the last record. 


0 ! 1 ! 2 ! 3 ! 4 : 5 ! B ! 7 : 

12345678901234567890123458789012345878901234567890123458789012345878901234567890 

TOTALS $564.30 $425.00 $139.30 
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If your program does not contain a primary input file, you must set on the LR indicator to 
end the execution of the program. If your program sets on the LR indicator, RPGII auto¬ 
matically sets on all control-level indicators just before total-time calculations. If the LR 
indicator is set on during total-time calculations, RPG II does not automatically sot on all 
control-level indicators. 

4.2.3 Matching-Record Indicator 

When you use more than one primary and secondary file, RPG II multifile logic supplies 
you with a method of selecting the next record to process. You can designate one or more 
fields in each record to be the matching fields (columns 61 and 62 of the Input specifica¬ 
tion). When the fields from a primary file and one or more of the secondary files im t ch, the 
matching-record (MR) indicator is set on. The MR indicator remains set on whil process¬ 
ing the records from the primary and secondary file that match. See Part I, Chapter 5 for a 
complete discussion of multifile processing. 

At the beginning of detail time, the MR indicator is set on or off, as determined by the 
matching status of the record to be processed. Therefore, at total time, the MR indicator 
reflects the matching status of the previous record with the record to be processed. See Part 
I, Chapter 5 for examples of using the matching-record indicator. 

4.2.4 External Indicators 

You can use external indicators to condition any operation in your program. External 
indicators, which are always represented by U1 through US, can also appear in columns 71 
and 72 of the File Description specification, and in columns 54 through 59 of the Calcula¬ 
tion specification. To use the external indicator, you must also assign the logical name 
RPG$EXT_INDS to an external indicator using the DEFINE or ASSIGN command, as 
shown in the following example: 

$ DEFINE RPG$EXT_INDS "external-indicator-list 11 

An external indicator is set on by specifying it in the external-indicator-list. An external 
indicator is set off by not specifying it in the external-indicator-list. 

The following example sets on external indicators Ul, U5, and U4 and sets off external 
indicators U2, U3, U6, U7, and U8. 

$ DEFINE RPG$EXT_INDS "54" 

When you use an external indicator to condition a file, the file is opened only when the 
external indicator is on. If the external indicator is off, input files being processed sequen¬ 
tially are treated as if the end-of-file was reached. Use the same external indicator as a 
conditioning indicator to control calculation and output operations for those files being 
processed by methods other than sequential processing. Otherwise, a run-time error will 
occur when you attempt input or output operations to a file that was not opened because 
the external indicator was off. 
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External indicators can also be used as resulting indicators. 


4.2.5 Halt Indicators 

You can use halt indicators (HI through H9) as record-identifying indicators, field indica¬ 
tors, or resulting indicators to stop a program when a specific condition occurs. When you 
use a halt indicator as a record-identifying indicator, a specific type of record causes the 
halt. 

The following example causes the program to check the character in position 80 of records 
read from the input file FILEIN. If the eightieth character is not a S, the halt indicator HI 
is set on and the program will halt execution. A run-time message is displayed saying that 
this indicator is on. 

Sequence (AA-ZZ, 01-99) 


Number (1-N) 

lOptional (0) Decimal positions 

IIRecord identifying indicator I Control level 



1 

1 

1 



1 

1 

Match field 


1 

1 

1 

+ Identifying codes + 

Format 

1 

1 

1 

Fid rec rel 

File 

1 

1 

1 

1 1 

1 (PB) 

1 Fie 1d 

1 

1 

1 

name 

1 

1 

1 

1 C C Cl 

1 Fie 1d 

1 name 

1 

1 

1 Field 

1 

1 

1 

1 

1 Z Z Zl 

1locationl1 

1 

1 

1 indicatrs 

II 

1 

1 

1 

Pos NDcPos NDcPos NDc 

IFr To 

1 1 

1 

1 

1 + - 0 


0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ##* * - # - #- .##-#-*# ######..,. 

IFILEIN AA HI 80NCS 
I 02 80 CS 

I 1 10 FIELD1 


ZK-4383-85 

When a halt indicator is used as a field indicator, a halt occurs because of erroneous input 
data. 
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The following program uses a halt indicator as a field indicator. When a record is read from 
the input file FILEIN, FIELD1 is checked for a negative value. If FIELD 1 contains a nega¬ 
tive value, H2 is set on. After this record has been processed, the program will halt. 


0 I 1 I 2I 3 I 1 I 5 I 6 I 7 M 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## * # # # * #—### # # # 


IFILEIN AA 01 

I 1 50FIELD1 H2 

C NH2 SORT FIELD1 FDL2 95 

ZK-4382-85 


When a halt indicator is used as a resulting indicator, a halt occurs when calculations pro¬ 
duce erroneous results during either detail time or total time. 

In the following example, if the field FIELD 1 is equal to zero, the halt indicator H4 is set 
on. After the current record has been processed, the program halts. 


Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

1 

1 

1 

1 

Result 1 
field 1 

1 1 

Decimal positions 

IHalf adjust (H) 

11 

11 Resulting 

11 indicators 

11+ - 0 

11> < = +- Comments —+ 

101 i 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # # 

# # 

# #- 

-##* # # # 

C FIELDi 

C NH4 FIELD2 

SUB 59.0 

DIV FIELDi 

FIELDi 

FIELDi 

H4 
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When a halt indicator is set on, a halt does not occur immediately. Before the program 
halts, it completes the current cycle and processes the record that caused the error 
condition. 

If any halt indicators are on after detail-time output, a run-time error occurs. 

Halt indicators can also be used as field-record-relation indicators and to condition calcu¬ 
lation and output operations. See Part II, Chapter 2 for more information on using halt 
indicators as field-record-relation indicators. 


/■ 
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4.3 Using Indicators As Fields 

The *IN, *IN,n and *INxx special words refer to predefined indicators and allow you to use 
those indicators in your program. Sections 4.3.1 and 4.3.2 describe each type of special 
word. 


4.3.1 *IN and *IN,n 

*IN is a predefined array with 99 one-position character elements. The elements in this 
array represent indicators 01 through 99. Use *IN,n, where n is the array index, to refer¬ 
ence an indicator. For example, *IN,54 refers to indicator 54. 

The elements in this array can assume only two character values — 1 and 0. If you refer¬ 
ence an indicator using *IN,n and the contents of the element are 0, the indicator is off. If 
the contents of the element are 1, the indicator is on. 

You can use either the array or the array element to reference an indicator anywhere any 
other one-character array or array element can be used. You cannot, however, specify the 
entire array *IN as the Result field of a PARM operation. To prevent unpredictable results 
when modifying an element in *IN, assign the character literal 0 or 1 to *IN. 

In the following example, the program tests whether the setting for indicator 15 is equal to 
the setting for indicator 20. In the next line, indicator 20 is set on. Using the MOVE opera¬ 
tion to transfer 1 to *IN,20 produces the same result as using the SETON operation code to 
set on indicator 20. 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

I Half adjust (H) 

II 

1 1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

!!><=+- Comments —+ 

0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

|l234567890i23456789012345678901234567890i2345678901234567890i2345678901234567890| 


## # # # # # #—### # # # 


C *IN,20 COMP #IN,15 99 

C MOVE '1' #IN,20 
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4.3.2 *INxx 

*INxx is a predefined one-position character field where xx represents any indicator except 
the IP (first-page), overflow, or external indicators. Like *IN, it can contain only the char¬ 
acter 0 or 1. 


You can use *INxx anywhere any other one-character field can be used, except as the 
Result field of a PARM operation. 
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In the following example, the value of the MR indicator is compared to the value of M. If 
they are the same, indicator 99 is set on. The MR indicator is represented as *INMR. 


1 _2_!_ 

112 13 1 

1 4 

1 5 1 

16 1 7 l| 

1123456789012345678901234567890123456789012345678901234567890123456789012345678901 

IFILE1 

I 

01 

1 

20 TEXT 


i 


19 

20 MATCH 

Ml 

IFILE2 

I 

02 

2 

21 TEXT 


I 


20 

21 MATCH 

Ml 

C 

*INMR COMP M 


99 
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Chapter 5 

Using Files 


A file is a collection of information, organized into groups or sections, called records. Each 
record is made up of one or more blocks of characters or numbers, called fields. 

This chapter explains the RPGII file organizations and record operations that are imple¬ 
mented through VAX Record Management Services. For additional information on file 
organization and file and record operations, see the VAX/VMS Record Management 
Services Reference Manual. 


5.1 File Names 

Columns 7 through 14 (File name) of the File Description specification define the file 
name. RPG II uses the entry in columns 7 through 14 (File name) and the entry in columns 
47 through 52 (Symbolic device) to associate the file name with the VAX/VMS file specifi¬ 
cation. The default type for an RPG II file is DAT. 

You can use a logical name for the entry in columns 47 through 52 (Symbolic device), and 
then assign a VAX/VMS file specification to the logical name. If you assign a full file speci¬ 
fication to the logical name, RPG II ignores the entry in columns 7 through 14 when deter¬ 
mining the file specification. If you do not assign the file-name part of the file specification 
to the logical name, RPG II uses the entry in columns 7 through 14 when determining the 
file specification. If you do not assign a file type to the logical name, RPG II uses DAT. 

If you do not specify an entry in columns 47 through 52, you can use a logical name as the 
entry in columns 7 through 14 for the VAX/VMS file specification. If you do not specify a 
logical name as the entry in columns 7 through 14, the file specification will consist of the 
file name in columns 7 through 14 and the file type DAT. 

The entry in columns 7 through 14 is used as the RMS default file name string. The entry 
in columns 47 through 52 (Symbolic device) is used as the RMS file name string. See the 
VAX/VMS Record Management Services Reference Manual for information about file¬ 
name strings and default file-name strings. 
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5.2 Record Formats 


The records in a file can be all the same length (fixed) or of different lengths (variable). 
Variable-lenoth records often use disk storage spa.ce more efficient^ 7 . The characteristics 
and requirements of individual applications should be carefully considered when you 
decide whether to use fixed-length or variable-length records. 

5.3 File Types 

You can use files in three ways: 

• As input to an RPGII program 

• As output from an RPG II program 

• As an update file where the records in the file are changed by the program 

5.4 File Organizations 

The organization of a file determines how the records in it are arranged. RPG II allows 
three different file organizations: 

• Sequential 

• Direct 

• Indexed 

Sections 5.4.1 through 5.4.3 describe these file organizations. 

5.4.1 Sequential Organization 

Sequential file organization is available on all types of devices. Sequential files contain 
records in the order that they were written. The first logical record in the file is always in 
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the first physical record position, the second logical record in the file is always in the sec¬ 
ond physical record position, and so on. If you need to access the fourth logical record, you 
can find it between the third and fifth physical records, as shown in Figure 5-1: 


1 

2 

3 

4 

5 


| 

I fourth record 
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Figure 5-1: Sequential File Organization 

You can retrieve records from a sequential file either sequentially, by reading through the 
entire file from beginning to end, or randomly, by using relative record numbers or an 
ADDROUTfile. 

5.4.2 Direct Organization 

Direct file organization is available on disk devices only. RMS handles RPG II direct files 
as files with relative file organization. A direct file consists of a series of fixed-length posi¬ 
tions (or cells) that are numbered consecutively from 1 to n. This number is the relative 
record number; it indicates the record’s position relative to the beginning of the file. (The 
relative record number of the first cell is always 1.) Each record you write is assigned to a 
specific cell within the file. For example, you can assign the second record to the fourth cell; 
its relative record number would be 4. This assignment can result in empty cells; there¬ 
fore, you must specify a record’s relative record number to access it. Figure 5-2 shows that 
cell number 2 and 5 are empty cells. 


cell no. - 

1 

2 

3 

4 

5 

6 

records - 

1 


2 

3 


4 



empty cell empty cell 
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Figure 5-2: Direct File Organization 
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Direct files can be accessed sequentially or randomly by using the CHAIN operation code 
or by using an ADDROUT file. When you access a direct file sequentially, empty cells are 
skipped. When you access a direct file randomly using the CHAIN operation, the indicator 
snecified in columns 54 and 55 of the Calculation specification will be set on for an empty 
cell. 

5.4.3 Indexed Organization 

Indexed file organization is available on disk devices only. Each record in an indexed file 
contains an index key value, as shown in Figure 5-3: 


index key value 


data 


record■ 
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Figure 5-3: Indexed File Organization 

An index key is a field within each record that is defined by its relative location within the 
record, and by its length. The index key is the primary means of locating records within 
the file. For example, you could use an employee’s badge number as the index key value for 
an employee record. The index key value in Figure 5-4 is the first six characters in the 
record, 768979. 


key 



Figure 5-4: Index Key Value 

You can retrieve a record from an indexed file by specifying its index key value. In fact, you 
can retrieve records in an indexed file either sequentially or randomly by using index key 
values, or randomly by using an ADDROUT file. 


5-4 Using Files 





Another way to access records from an indexed file is sequentially within limits. See Sec¬ 
tion 5.5 for more information on accessing records from indexed files. 


5.5 File Access Methods 

There are several ways you can access the records in a file, depending on its organization. 
Table 5-1 lists file organizations and the methods you can use to retrieve records. 

Table 5-1: File Access Methods 


File Designation 

Organization 

Access Method 

Primary 

Sequential 

Sequentially 

Secondary 


Randomly by ADDROUT file 1 

Demand 

Direct 

Sequentially 

Full-procedural 


Randomly by ADDROUT file 1 


Indexed 

Sequentially 

Sequentially by key 

Sequentially within limits 

Randomly by ADDROUT file 1 

Chained 

Sequential 

Randomly by relative record number 2 

Full-procedural 

Direct 

Randomly by relative record number 


Indexed 

Randomly by key 


1 You cannot process demand or full-procedural files using an ADDROUT file. 

2 You can access the records in a sequential file randomly by relative record number only 
if the records are fixed-length and the file resides on disk. 

Although you cannot change the organization of a file after you have created it, you can 
change the file access method each time you use the file. The method you use depends on 
how many records your file contains and how often you need to access a record . Use the 
following guidelines in selecting a file organization and access method: 

• If you always process all the records in a file from beginning to end (as in a payroll 
application), use a sequential file and access the records sequentially. 

• If you need to access some or all records under changing or unpredictable conditions 
(as in a transaction processing system), use an indexed or direct file and access the 
records randomly. 

Sections 5.5.1 through 5.5.7 describe each file access method and provide programming 
guidelines for each. 
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5.5.1 Sequential Access 

When you access a file sequentially, each input operation retrieves the next record in the 
file, regardless of the file organization, until either the end of the file is reached or the 
program terminates. For an indexed file, records are retrieved in primary key order. 

To specify sequential access, you must make the following entries in its File Description 
specification: 

• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for 
input or for update. 

• Column 16 (File designation) - Specify P, S, D, or F to indicate whether the input file is 
primary, secondary, demand, or full-procedural. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) — Specify the length of fixed-length records or 
the maximum length of variable-length records. 

The following example specifies the name of a file, INPUT, designated as an input primary 
file with fixed-length records and a record length of 60 bytes: 


Mode (LR) 

I Key length 



Type (I0UD) 

1 

Record address type (API) 


Addtn(AU) 


IDes (PSRCTD) 

1 

lOrganization (IT,i-9) 


1 Expand 


IIEOF (E) 

1 

IIOverflow indicator 


11 Share 


IllSecj (AD) 

1 

III Key location 


111 Rewnd 

File 

IMIFmt (FV) 

1 

III 1 Extension (EL) 


III 1 

name 

1111IBlk Rec 

1 

III 1 1 Device Symb Tape 

Core 

III 1 File 

1 

Mill len len 

1 

III 1 Icode dev label 

index 

III Icond 

FI 

MINI 1 

1 

III 1 II II 

1 

III II 


011 121314 1. 516171 

1234567890i234567890i234567890i2345678901234567890i234567890i234567890i234567890 


## **#### - # -##-*#* #-## # -###,## , . 

FINPUT IP F 60 DISK 


ZK-4394-85 


5-6 Using Files 















5.5.2 Sequential Access by Key 

You can process only indexed primary, secondary, demand, and full-procedural files 
sequentially by key. VAX RMS reads records in ascending key sequence until it reaches 
the end of the file or until the program terminates. 

To specify sequential access by key for a file, you must make the following entries in its 
File Description specification: 

• Column 15 (File type)-Specify I or U to indicate whether the file is to be open for input 
or for update. 

• Column 16 (File designation)-Specify P, S, D, or F to indicate whether the input file is 
primary, secondary, demand, or full-procedural. 

• Column 19 (Record format)-Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length)-Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Columns 29 and 30 (Key length)-Specify the length of the key field. 

• Column 31 (Record address type)-Specify either A or P to tell RPG II that the index 
keys are in character (A) or packed decimal (P) data format. 

• Column 32 (File organization)-Specify I to indicate that the file is an indexed file. 

• Columns 35 through 38 (Key location)-Specify the starting character position of the 
key field. 

The following example specifies a primary input file, INPUT, with fixed-length records 60 
bytes long. The file organization is indexed with its index keys in packed decimal data 
format. 


Mode (LR) 

I Key length 



i r-.i 

Type ( I0UD) II 

-3 * ci 15 vii 

Record address type (API) 


Addtn(AU) 


IDes (PSRCTD)11 

lOrganization (IT,1-9) 


1 Expand 


IIEOF (E) II 

MOverflow indicator 


11 Share 


IllSect (AD) II 

111 Key location 


111 Rewnd 

File 

MilFnt (FV) II 

III 1 Extension (EL) 


III 1 

name 

1111IBlk Rec 11 

III 1 1 Device Symb Tape 

Core 

III IFile 

1 

Mil lien len II 

III 1 Icode dev label 

index 

111 Icond 

FI 

111111 1 II 

III 1 II II 

1 

III II 

0 1 

11 2 1 

1 3 1 4 1 5 

1 i 

i 1 m i 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## ##*### —#— *#-##* #—## # # . #-#*#.## 

FINPUT IP F 60 3PI 1 DISK 
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5.5.3 Sequential Access Within Limits 

You can process indexed files sequentially within limits by creating a record-limits file 
that specifies a range of index keys in each record. 


record 


record-limits file 


A 

data 

B 

data 

C 

data 

D 

data 

E 

data 

F 

data 


file 


first record 

• second record 


high key 
low key 


key 
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Figure 5-5: Sequential Access Within Limits 

In Figure 5-5, the first record in the record-limits file causes RPG II to retrieve those 
records whose keys are greater than or equal to the low key (C) and less than or equal to 
the high key (E). When the program reaches a record with a key value greater than E or 
reaches the end-of-file, it reads the next record from the record-limits file to get a new high 
and low range. The second record in the record-limits file causes the program to retrieve 
those records whose keys are greater than or equal to the low key (E) and less than or equal 
to the high key (G). The indexed file is processed until it reaches the end of the record- 
limits file or the program terminates. 

When using a record-limits file to process indexed files, observe the following rules: 

• In the record-limits file, specify only one set of limits per record. 

• The record length must be at least twice the length of the record key. 

• The low key must begin in character position 1, and the high key must immediately 
follow the low key. 
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• The length of the high and low keys must be the same, and must be equal to the length 
of the key field in the file to be processed. 

• Numeric keys can contain leading zeros. 

• Alphanumeric keys can contain blanks. 

To access a file sequentially within limits, you must make the following entries in its File 
Description specifications: 

• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for 
input or for update. 

• Column 16 (File designation) - Specify P, S, D, or F to indicate whether the input file is 
primary, secondary, demand, or full-procedural. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Column 28 (Access mode) - Specify L to indicate that the indexed file is to be processed 
sequentially within limits. 

• Columns 29 and 30 (Key length) - Specify the length of the key field. 

• Column 31 (Record address type) - Specify either A or P to indicate that the index 
keys are in character (A) or packed decimal (P) data format. 

• Column 32 (File organization) - Specify I to indicate that the file is an indexed file. 

• Columns 35 through 38 (Key location) - Specify the starting character position of the 
key field. 


Using Files 


5-9 



The following example specifies an input secondary file, INPUT, with fixed-length records 
60 bytes long. This file is to be processed sequentially within limits. The file organization is 
indexed, the key field is three bytes long beginning in character position 1, and the keys 
are in character format. 


Mode (LR) 




1 Key length 




Type (I0UD) 

II Record address type (API) 


Addtn(AU) 


IDes (PSRCTD) 

II (Organization (IT,1-9) 


1 Expand 


IIEOF (E) 

II llOverflow indicator 


11 Share 


IllSect (AD) 

II III Key location 


111 Rewnd 

File 

IMIFmt (FV) 

II III 1 Extension (EL) 


III 1 

name 

1111 IBlk Rec 

II III 1 1 Device Symb Tape 

Core 

III IFile 

1 

II111len 1en 

II III 1 Icode dev label 

index 

III Icond 

FI 

Mini i 

II III 1 II II 

1 

III II 

0 1 

1 1 2 

1 3 1 4 1 5 

1 ( 

S 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

######—#— 

##-### #—## # #. 

.#- 

-###,#* 


FINPUT IS F 


60L 3AI 


i DISK 
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To access a file sequentially within limits, you must make the following entries for the 
record-limits file in its File Description specification: 

• Column 15 (File type) - Specify I to indicate that the file is to be open for input. 

• Column 16 (File designation) - Specify R to indicate that the file named in columns 7 
through 14 is a record-limits file. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24-27 (Record length) - Specify the length of fixed-length records or the 
maximum length of variable-length records. 

• Columns 29 and 30 (Key length) - Specify the length of the key field. 

• Column 31 (Record address type) - Specify either A, P, or blank to indicate that the 
index keys are in character (A), packed decimal (P), or the same data format as the file 
being processed by the record-address file (blank). 

• Column 39 (Extension) - Specify E to cause the system to look for an Extension 
specification. 

You must also make the following entries for the record-limits file in its Extension 
specification: 

• Columns 11 through 18 (From file name) - Specify the name of the record-limits file. 

• Columns 19 through 26 (To file name) - Specify the name of the file to be processed by 
the record-limits file. 
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The following example specifies the File Description and Extension specifications for 
processing a file sequentially within limits: 


o i 1 i 2 i 3 i 4 i 5 i 6 i i n 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FIDXA12 IR F 6 3A EDISK 

FIDXI12 IP F 60L 3AI i DISK! 
E IDXA12 IDXI12 
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An indexed demand or full-procedural file can also be processed sequentially within limits 
using the SETLL operation. See Part II, Chapter 3 for information on the SETLL operation 
code. 

5.5.4 Random Access 

Accessing records randomly allows you to retrieve or write a record anywhere in the file. 
To do this, you must specify the record location using: 

• Relative record numbers 

• Keys 

• ADDROUT file 

The method you use depends on the organization of the file. Sections 5.5.4.1 through 
5.5.4.3 explain these methods. 

5.5.4.1 Random Access by Relative Record Number 

You can randomly access records in sequential and direct files by specifying relative record 
numbers that identify records relative to the beginning of the file. For example, the rela¬ 
tive record number for the fifth record is 5. Accessing a sequential file using this method 
requires that the records be of fixed length and that the file reside on disk. 

To access a file randomly by relative record number, you must make the following entries 
in its File Description specification: 

• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for 
input or for update. 

• Column 16 (File designation) - Specify C or F to indicate whether the file named in 
columns 7 through 14 is a chained or full-procedural file. 

• Column 19 (Record format) - Specify F or V to describe the record format. 
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• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Column 28 (Mode) - Specify R to cause RPG II to access the file randomly, using a 
relative record number. 

You must also make the following entries for the file in its Calculation specification: 

• Columns 18 through 27 (Factor 1) - Specify the relative record number of the record 
you want to retrieve. 

• Columns 28 through 32 (Operation code) - Specify the CHAIN operation code. Use an 
indicator in columns 54 and 55 to signal an empty cell condition for a direct file. Oth¬ 
erwise, attempting to CHAIN to an empty cell will cause a run-time error. 

• Columns 33 through 42 (Factor 2) - Specify the name of the file that contains the 
record you want to retrieve. 

The following example randomly accesses the direct file RAN07A by relative record num¬ 
ber. The primary input file RANI07 provides the record numbers in the field ITEM#. 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FRANI07 

IP 

F 

13 

DISK 


FRAN07A 

UC 

F 

10R 

DISK 


FRAN07B 

0 

F 

30 

PRINTER 


IRANI07 

AA 

01 




I 




i 

11 STORE 

I 




13 

130ITEM# 

IRAN07A 

AB 

02 




I 




1 

10REC# 

I 




3 

50ACCESS 

I 




7 

10 VALUE 

C 


ITEM# 

CHAINRAN07A 


50 

C 50 



GOTO HANDLR 



C 


1 

ADD ACCESS 

ACCESS 


C 



SET0N 


40 

C 



EXCPT 



C 



SET0F 


40 

C 


HANDLR 

: TAG 



C 50 



SET0N 


LR 

ORAN07A 

E 


02 40 



0 



REC# 

1 


0 



ACCESS 

5 


0 



VALUE 

10 


ORAN07B 

H 

22 

1PN40 



0 




22 'STORE PURCHASES 

0 

D 


01N40 



0 



STORE 

14 


0 



ACCESS 

20 


0 



VALUE 

27 
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5.5.4.2 Random Access by Key 

You can randomly retrieve records from an indexed file by specifying their index keys. 

To access a file randomly by key, you must make the following entries in its File Descrip¬ 
tion specification: 

• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for 
input or for update. 

• Column 16 (File designation) - Specify C or F to indicate whether the file named in 
columns 7 through 14 is a chained or full-procedural file. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Column 28 (Mode) - Specify R to tell RPG II to access records randomly, using index 
key values. 

• Columns 29 and 30 (Key length) - Specify the length of the key field. 

• Column 31 (Record address type) - Specify either A or P to indicate that the index 
keys are in character (A) or packed decimal (P) data format. 

• Column 32 (File organization) - Specify I to indicate that the file is an indexed file. 

• Columns 35 through 38 (Key location) - Specify the starting character position of the 
key field. 

You must also make the following entries for the file in its Calculation specification: 

• Columns 18 through 27 (Factor 1) - Specify the index key of the record you want to 
retrieve. 

• Columns 28 through 32 (Operation code) - Use the CHAIN operation code. The record 
you specify can be read from the file either during detail-time or total-time calcula¬ 
tions. Specify an indicator in columns 54 and 55 to signal a record-not-found condi¬ 
tion. Otherwise, a record-not-found condition will cause a run-time error. 

• Columns 33 through 42 (Factor 2) - Specify the name of the file to be processed. 
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The following example randomly accesses the indexed file GROCER using keys. The 
primary input file STORES provides the keys in the field ITEM#. 


011121314151617 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FSTORES 

IP 

F 

13 

DISK 



FGROCER 

IC 

F 

10R 1AI 1 

DISK 



FREP0RT 

0 

F 

30 

PRINTER 


IST0RES 

AA 

01 





I 





1 

11 STORE 

I 





13 

130ITEM# 

IGROCER 

AB 

02 





I 





1 

10REC# 

I 





3 

50C0UNT 

I 





7 

10 VALUE 

C 


ITEM# 

CHAINGR0CER 



50 

C 50 



SET0N 



LR 

OREPORT 

H ; 

22 

1PN40 




0 




22 

'STORE PURCHASES 

0 

D 


01N40 




0 



STORE 

14 



0 



COUNT 

20 



0 



VALUE 

27 
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5.5.4.3 Random Access by ADDROUT File 

Another way to process files is by using an ADDROUT file. You can use a record-limits file 
to process only indexed files. You can use an ADDROUT file to process sequential, direct, or 
indexed files. 
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ADDROUT files are created by the VAX SORT/MERGE Utility when you use the 
PROCESS = ADDRESS qualifier. You specify a field or fields in the record by which the 
utility sorts the records, as shown in Figure 5-6: 



i 

field to sort 
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Figure 5-6: Random Access by ADDROUT File 

The utility sorts the records and places the disk addresses of the sorted records in an 
ADDROUT file, as shown in Figure 5-7: 



address of A 
address of B 
address of C 
address of D 
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Figure 5-7: ADDROUT File 
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The program reads the records (addresses) in the ADDROUT file sequentially. Each record 
in the ADDROUT file corresponds to a record in the original file. The addresses of the 
records are referred to as Record File Addresses (RFAs) by RMS. For additional informa¬ 
tion on RFAs, see the VAX/VMS Record Management Services Reference Manual . 

To access a file using an ADDROUT file, you must make the following entries in the File 
Description specification for the file to access: 

• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for 
input or for update. 

• Column 16 (File designation) - Specify P or S to indicate that the file named in col¬ 
umns 7 through 14 is primary or secondary. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Column 28 (Mode) - Specify R to cause RPGII to access records randomly. 

• Columns 29 and 30 (Key length) - Specify the length of the key field if you plan to 
access an indexed file. 

• Column 31 (Record address type) - Specify I to cause the program to access the file 
according to the ADDROUT file. 

• Column 32 (File organization) - Specify I if you plan to access an indexed file. 

• Columns 35 through 38 (Key location) - Specify the starting character position of the V 

key field if you plan to access an indexed file. 

To access a file using an ADDROUT file, you must make the following entries for the 
ADDROUT file in its File Description specification: 

• Column 15 (File type) - Specify I to indicate that the file is to be open for input. 

• Column 16 (File designation) - Specify R to indicate that the file named in columns 
7 through 14 is an ADDROUT file. 

• Column 19 (Record format) - Specify F to describe the record format. 

• Columns 24 through 27 (Record length) - Specify 6, because record addresses are 
always 6 bytes in length. 

• Columns 29 and 30 (Key length) - Specify 6, because record addresses are always 
6 bytes in length. 

• Column 31 (Record address type) - Specify I to indicate that this is an ADDROUT file. 
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• Column 32 (File organization) - Specify T to indicate an ADDROUT file. 

• Column 39 (Extension) - Specify E to cause RPG II to look for an Extension 
specification. 

You must also make the following entries for the ADDROUT file in the Extension 
specification: 

• Columns 11 through 18 (From file name) - Specify the name of the ADDROUT file. 

• Columns 19 through 26 (To file name) - Specify the name of the file to be processed by 
the ADDROUT file. 

The following example specifies the ADDROUT file IDXA13 and the file IDXI13 to be 
accessed by the ADDROUT file: 


0111213141516171 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 
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5.5.5 Sequential Access and/or Random Access by Key 

A full-procedural file allows you to read a file both randomly and sequentially. If the full- 
procedural file is an indexed file, then you can read the file randomly by key using the 
CHAIN or SETLL operation, and you can read the hie sequentially. 

To specify an indexed full-procedural file, make the following entries for the file in its File 
Description specification: 

• Columns 7 through 14 must contain the file name. 

• Column 15 (File type) - Specify I or U to indicate that the file is open for input or 
update. 

• Column 16 (File designation) - Specify F to indicate a full-procedural file. 

• Column 32 (File organization) - Specify I to indicate an indexed file. 

• Columns 40 through 43 (Device code) - Specify DISK. 
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The following example specifies the full-procedural file FPFJ01 to be accessed by a CHAIN 
operation with the key specified in FPFI01. The file FPFJ01 is then processed sequentially 
from that point on. 


0I1I2I3I4I5 I6I7I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FTTY 

FFPFI01 

FFPFJ01 

FFPF01A 

LFPF01A 

IFPFI01 

I 

IFPFJ01 

I 

I 

I 

I 

C 

c 

c 

C 98 
C 98 
C 
C 

C NLR 
C NLR 
C 

0FPF01A 
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0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


D F 80 TTY 

ID F 04 DISK 

IF V 47R04AI 1 DISK 

0 V 73 LPRINTER 

55FL 500L 

1 4 PARTNO 

1 4 PARTNO 

5 39 DESCR 
40 43 PRICE 
44 47 AMOUNT 

READ FPFI01 

PARTNO CHAINFPFJ01 98 

EXCPT 

'BAD' DSPLYTTY 

GOTO END 

LOOP TAG 

READ FPFJ01 LR 

EXCPT 
GOTO LOOP 
END TAG 

H 201 IP 

32 'PARTS SUMMARY INVENTORY' 

H 10 IP 

11 'PART NO' 

30 'DESCRIPTION' 

H 00 IP 

30 '_' 

H 01 IP 


PARTNO 9 
DESCR 47 
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5.6 Creating Files 


There are a variety of ways to create files with sequential, direct, and indexed organiza- 
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You can create sequential files by writing records, one after another, to an output file. Once 
a sequential file is created, you can use it as an input file, an update file, or an output file 
with the ADD option. 


5.6.1 Creating Sequential Files 

To create a sequential file, you must make the following entries in the File Description 
specification: 

• Column 15 (File type) - Specify O to indicate the creation of an output file. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

The following program creates a sequential file OUT60A: 


1 o 1 

1 

1 

2 1 

3 1 4 

1 

5 1 6 1 7 II 
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24 
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5.6.2 Creating Direct Files 

You can create a direct file by specifying a chained output file. To do this, you must make 
the following entries in its File Description specification: 

• Column 15 (File type) - Specify O to indicate the creation of an output file. 
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• Column 16 (File designation) - Specify C to indicate that the file named in columns 
7 through 14 is a chained file. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Column 28 (Mode) - Specify R to cause RPGII to load a direct file. 

The following program creates a direct file OUT60B with variable-length records: 
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5.6.3 Creating Indexed Files 

You can create an indexed file either in ordered key sequence or in unordered key 
sequence. If you specify unordered, you can write records to an indexed file in any order, 
regardless of the key sequence. If you specify ordered, you must write records in the order 
of their key; the order must be ascending. Once the file is created, VAX RMS sorts the 
index keys in ascending order, regardless of the way they were written. 

To create an indexed file in ordered sequence, you must make the following entries in its 
File Description specification: 

• Column 15 (File type) - Specify O to indicate the creation of an output file. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 
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• Columns 29 and 30 (Key length) - Specify the length of the key field. 

• Column 31 (Record address type) - Specify either A or P to indicate that the index 
keys are in character (A) or packed decimal (P) data format. 

• Column 32 (File organization) - Specify I to indicate an indexed file. 

• Columns 35 through 38 (Key location) - Specify the starting character position of the 
key field. 

The following program creates an indexed file OUT60A with an alphanumeric key that is 
three bytes long. The key begins in character position 1 of each record. 


0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
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To create an indexed file in unordered sequence, make the same entries as for an ordered 
sequence and specify U in column 66 (Unordered). 


5.7 Adding Records to Files 

After you create a file, it may be necessary to add new records to the file. You can add 
records to a file at detail-time or total-time output, or by using exception output. Sections 
5.7.1 through 5.7.3 explain how to add records to files on the basis of their file organization. 
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5.7.1 Adding Records to a Sequential File 

Because the location of each record in a sequential file is fixed in relation to all others, 
there is no unused space where a new record might be inserted. Therefore, you can add 
records to a sequential file only at the end of the file, as shown in Figure 5-8: 
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Figure 5-8: Adding Records to a Sequential File 

To add a record to the end of a sequential file, you must make the following entries in its 
File Description specification: 

• Column 15 (File type) - Specify O to indicate the creation of a new record. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Column 66 (File addition) - Specify A to cause RPGII to add new records to the file. 
You must also make the following entries in the file’s Output specification: 

• Columns 7 through 14 (File name) - Define the output file name. 

• Columns 16 through 18 - Specify ADD to identify the record to be added. 

The following example accepts input from the terminal and writes records to the end of the 
file LOG: 


01 1I2I3I4I5I6I7I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FINPUT IP F 80 

FLOG OF 80 

IINPUT 01 

I 

0L0G DADD 01 
0 


TTY 

DISK 


DATA 80 


80 DATA 


A 
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5.7.2 Adding Records to a Direct File 

To add a new record to a direct file, you can either specify the relative record number of an 
empty cell or add the record at the end of the file, as shown in Figure 5-9: 



1 


2 

3 


4 


* i 


or 
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Figure 5-9: Adding Records to a Direct File 

To add records to empty cells in a direct file, you must make the following entries for the 
file in its File Description specification: 

• Column 15 (File type) - Specify I or U to indicate that the file is open for input or 
update. 

• Column 16 (File designation) - Specify C or F to indicate a chained or full-procedural 
file. 

• Column 19 (Record format) - Specify F or V to describe the record format. 

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or 
the maximum length of variable-length records. 

• Column 28 (Mode) - Specify R to access records randomly, using a relative record 
number. 

• Column 66 (Addition) - Specify A to add records to the file. 

You must also make the following entries in the Calculation specification: 

• Columns 18 through 27 (Factor 1) - Specify the relative record number of the empty 
cell. 

• Columns 28 through 32 (Operation code) - Specify the CHAIN operation code. Use an 
indicator in columns 54 and 55 to see whether the cell is empty. The indicator will be 
set on if it is. If the cell is empty and an indicator is not specified, a run-time error 
occurs. 

• Columns 33 through 42 (Factor 2) - Specify the name of the file to which you want to 
add the record. 
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Finally, you must make the following entry in the Output specification: 

• Columns 7 through 14 (File name) - Define the output file name. 

• Columns 16 through 18 - Specify ADD to identify the record to add. 

The output operation must follow the CHAIN operation, but before the next CHAIN opera¬ 
tion. If not, the output will be to the cell specified by the second CHAIN operation. 

The following example reads a primary input file and adds records to the direct file 
DIRECT. The input field RECNO specifies the record cell to which the field is written. 


0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 
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ZK-4405-85 


5.7.3 Adding Records to an Indexed File 

If the file is an indexed file, you can add records at any location. The key values for the new 
records are placed in the index and the entire index is sorted in ascending sequence. 

NOTE 

When adding records to an indexed file, you cannot specify A in column 66 
(File addition) of the File Description specification for indexed files processed 
sequentially within limits or processed by an ADDROUT file. 


You can add new records to an indexed file while processing the file by specifying an A in 
column 66 (File addition) of the File Description specification. The file can be an input or 
update file that is processed sequentially or randomly. If you want only to add records, you 
can specify an output file. 

You must also make the following entry in the Output specification: 

• Columns 7 through 14 (File name) - Define the output file name. 

• Columns 16 through 18 - Specify ADD to identify the records to be added. 
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The following program adds records to an indexed file using the ADD option on the Output 
specification: 


011121314151ft _I_ 1 _L 
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5.8 Updating Records in Files 

RPGII allows you to update the records in a primary, secondary, demand, full-procedural 
or chained file. RPG II allows you to update the records in a sequential file only if the 
records are of fixed length. You can update a record in a primary or secondary file only once 
during the program cycle at detail time. Unlike other types of update files, records in a 
chained, full-procedural or demand file can be updated at detail time or at total time. 

To update a record, you must retrieve the record you want to change, change the contents, 
and then write the record back to the file. You need only specify the fields to be changed in a 
record. The remainder of the record is rewritten, using the data that was read into the 
input buffer. 

You can use a data structure to update a record. See Part I, Chapter 12 for an example of 
updating files with data structures. 

RPG II allows you to change the length of a variable-length record being updated. RPG II 
determines the length of the record by using the highest End position (columns 40 through 
43 of the Output specification) of any field in the record. If you need to change the contents 
of a field in the middle of a variable-length record, but do not wapt to change the length of 
the record, you must define the length of the record by defining a one-character field in the 
last character position of the record. 

The following example updates records in the master file MASTER. MASTER contains 
two different record types of different lengths. Both records contain the field that must be 
updated EMP# in different character positions. The fields LNGTH1 and LNGTH2 ensure 
that the records are updated using the correct length. The records of type 01 are 80 charac¬ 
ters long. The records of type 02 are 60 characters long. 
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To update the records in a direct or indexed file and simultaneously add new records, com¬ 
plete the following entries for the file in its File Description specification: 

• Column 15 (File type) - Specify U to indicate that the file is open for update. 

• Column 66 (File addition) - Specify A to add new records to the file. 

You must also define both Input and Output specifications for the file to be updated. Enter 
ADD in columns 16 through 18 of those Output specifications that identify the records to 
be added. The output records without ADD in columns 16 through 18 identify those records 
to be updated. 
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5.8.1 Updating a File Sequentially or Randomly by Key 

You can update records in an indexed file randomly by key, sequentially, or both randomly 
and sequentially if the file is defined as a full-procedural file. To specify an indexed full- 
procedural file to be processed in the update mode, make the following entries for the file in 
its File Description specification: 

• Column 15 (File type) - Specify U to indicate that the file is open for update. 

• Column 16 (File designation) - Specify F to indicate a full-procedural file. 

• Column 32 (File organization) — Specify I to indicate an indexed file. 


5.9 Deleting Records From Files 

You can delete records only from update direct and indexed files. To prevent the deletion of 
needed records, perform the following steps: 

• Retrieve the record. 

• Evaluate its contents. 

• Based on the results of the evaluation, set an indicator to control deletion of the 
record. 

The last record retrieved from the file is the one that is deleted when you specify DEL in 
columns 16 through 18 of the Output specification. You do not need to describe any fields in 
the output record, because the operation deletes the entire record. 

The following example deletes a record in the master file MASTER, depending on the keys 
read from the file DELETE: 
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5.10 Processing Files With Matching Records 

Matching fields can be used with primary and secondary files to check the sequence of 
records and to define the order in which records are selected from multiple files. 

To use matching fields to verify that the records in the file are in sequence (either ascend¬ 
ing or descending), you define one or more fields to be checked by specifying a matching 
field value (Ml through M9) in columns 61 and 62 in the Input specification. Then, your 
program checks the sequence by comparing the matching field of one record with the 
matching field of the previous record. If the field is out of order, a run-time error occurs. 

5.10.1 Checking Record Sequence for One Record Type 

You designate a record sequence by specifying A or D (ascending or descending) in column 
18 of the File Description specification. Assign a matching field value (Ml through M9) to 
one or more fields you want to use as matching fields in columns 61 and 62 (Matching field) 
of the Input specification. When you specify more than one matching field, assign M9 to the 
most important field. Your program considers all matching fields as one contiguous field 
with the M9 field in the leftmost position, next to the M8 field, and so on, until you reach 
Ml, even though the fields may not be adjacent in the record or in numeric (M9 to Ml) 
order. 

5.10.2 Checking Record Sequence for More Than One Record Type 

The fields in a record of one type can be in a different order from the fields in other record 
types in the same file. Suppose a payroll file consists of two different record types, one type 
representing commission payment and the other type representing salary. All employee 
records are to be in ascending sequence according to district (DSTRCT). Records in a dis¬ 
trict are to be in ascending sequence according to department and employee number. 
Therefore, three fields (DSTRCT, DEPT, and EMPNUM) must be checked in each record. 
M3 is assigned to DSTRCT, the most important field; M2 is assigned to DEPT, the next 
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most important field; and Ml is assigned to EMPNUM, the least important field. Refer to 
the following example: 
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First, the program determines the record type. Then, it looks at the matching fields for the 
same record type. 

In the example above, the same three matching fields (DSTRCT, DEPT, and EMPNUM) 
appear in both record types and are the same length. 

The length of matching fields assigned to the same match code must be the same length for 
each record type. Table 5-2 shows that this is true for the following example: 
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8 9 DSTRCT 

M3 

— 

1 

I 





25 27 EMPNUM 

Mi 
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Table 5-2: Matching Field Lengths 


Record 

Type 

Matching 

Field 

Field 

Location 

Field 

Length 

first 

DSTRCT 

6 to 7 

2 


DEPT 

1 to 3 

3 


EMPNUM 

25 to 27 

3 

8 total 

second 

DSTRCT 

8 to 9 

2 


DEPT 

1 to 3 

3 


EMPNUM 

25 to 27 

3 

8 total 


Matching fields need not be specified for all the record types in a file. 


5.10.3 Using Matching Fields With Field-Record-Relation Indicators 

Although there may be different record types in a file, very often the fields for each record 
type are the same. Many fields have the same name, contain the same data, and are in the 
same character positions for all the record types in a file. When only a few fields differ, you 
can describe more than one record type in an OR relationship. Refer to the following 
example: 

Sequence (AA-ZZ, 01-99) 



1 Number (1-N) 





1 lOptional (0) 


Decimal positions 


1 II Record identifying indicator 

1 

Control level 


1 III 


1 

1 Match/chain field 


1 111+ Identifying codes + 

Format 

1 

1 1 Field rec rel 

File 

1 III 1 1 

1 

1 Fie 1 d 

1 1 1 

name 

1 III 1 C C Cl 

1 Fie 1d 

Iname 

1 1 1 Field 

1 

1 III 1 Z Z Zl 

1locationl1 

1 1 1 indicators 

II 

1 111 Pos NDcPos NDcPos NDc 

IFr To 

11 

1 1 1 + - 0 


0 I 1 


123456789012345678901234567890123456789012345678901234567890123456789012345678901 


** * ### *— #— #— , ## — # —## ##*### .... 

IPAYR0LL AA 01 80 CS 

I OR 02 80 CM 

ZK-4411-85 
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You specify common fields only once, because they apply to both record types. The field- 
record-relation indicators specified in columns 63 and 64 of the Input specification identify 
the fields unique to a particular record type. Therefore, the COMM field in the following 
example is associated with record type 01 and the SALARY field is associated with record 
type 02. Because DSTRCT, DEPT, and EMPNUM are matching fields used in checking the 
sequence of the records in the PAYROLL file and because Ml, M2, and M3 are described 
only once in columns 61 and 62 without any field-record-relation indicators in columns 63 
and 64, they apply to both record types (01 and 02) as shown in the following example: 

Sequence (AA-ZZ, 01-99) 



1 Number (1-N) 




1 [Optional (0) 

Decimal positions 


1 II Record identifying indicator 

1 III 

1 

Control level 


1 

1 Match/chain field 


1 1II + Identifying codes + Format 

1 III 1 II 

i 

1 1 Field rec rel 

File 

IField 

1 1 1 

name 

1 III 1 C C Cl IField 

Iname 

1 1 1 Field 

1 

1 III 1 Z Z Zl 1 location 11 

1 1 1 indicators 

II 

1 III Pos NDcPos NDcPos NDc IFr To 

II 

1 1 1 + - 0 

10 1 1 1 2 1 3 1 4 1 51 6 1 7 II 

|i23456789012345678901234567890i234567890i234567890i23456789012345678901234567890| 


## 

# 

### #- 

— 

#— #— 

.##—* 

—## # 

# # # * # .... 

IPAYR0LL 

A A 

01 

80 

cs 




I 

OR 

02 

80 

CM 




I 





1 

3 DEPT 

M2 

I 





8 

9 DSTRCT 

M3 

I 





25 

27 EMPNUM 

Ml 

I 





14 

152C0MM 

01 

I 





13 

172SALARY 

02 
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If one of the matching fields is in a different record position for each record type, you must 
assign matching field entries, as shown in the following example: 

Sequence (AA-ZZ, 01-99) 



1 Number (i-N) 





1 lOptional (0) 


Decimal positions 


1 II Record identifying indicator 

1 

Control level 


1 III 


1 

1 Match/chain field 


1 111+ Identifying codes + 

1 III 1 1 

Format 

1 

1 1 Field rec rel 

File 

1 

IField 

1 1 1 

name 

1 III 1 C C Cl 

IField 

Iname 

1 1 1 Field 

1 

1 III 1 Z Z Zl 

1 location 11 

1 1 1 indicators 

II 

1 III Pos NDcPos NDcPos NDc 

IFr To 

II 

1 1 1 + - 0 


0 I i 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#* # 

### #- 

— 

#— 

#— 

.##—#- 

-—## * 

# # ■ 

IPAYR0LL AA 

01 

80 

cs 





I OR 

I 

02 

80 

CM 


1 

3 EMPNUM 

Ml 

I 





20 

21 DSTRCT 

M3 

I 





6 

72C0MM 

01 

I 





10 

12 DEPT 

M201 

I 





5 

7 DEPT 

M202 

I 





10 

142SALARY 

02 
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For a 01 record type, matching field DEPT is in Field location 10 through 12. For a 02 
record type, matching field DEPT is in Field location 5 through 7. 

5.10.4 Using Matching Fields to Process More Than One File 

The processing of a primary file with one or more secondary files is called multifile process¬ 
ing. In multifile processing without matching fields, RPGII first reads all the records from 
the primary file, then reads all the records from each secondary file in the same order in 
which they are specified in the File Description specification. By using matching fields, 
your program can select the records from the secondary file before selecting the records 
from the primary file, based on the value of their matching fields. 

When you use matching fields to process more than one file, the program selects records 
according to the contents of the matching fields, as follows: 

• One record is read from every file and the matching fields are compared. If the records 
are in ascending order, the record with the lowest matching field value is selected for 
processing. If the records are in descending order, the record with the highest match¬ 
ing field value is selected for processing. 

• When a record is selected from a file and processing of that file takes place, the next 
record from the file is read. The new record is then compared with the other records 
not selected in the previous cycle. 
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You can combine records with and without matching fields in the same file. Records with¬ 
out matching fields are processed before records with matching fields. If two or more of the 
records being compared have no matching fields, selection of those records is determined 
by the priority of their files, as follows: 

• The records in primary files are processed before the records in secondary files. 

• The records in secondary files are processed in order of appearance in the File Descrip¬ 
tion specifications. 

In the following example, the matching fields from a primary file are compared with the 
matching fields from a secondary file to select records in ascending sequence. The letters 
represent the data in the matching fields. 

Table 5-3: Matching Field Values 


Matching Field Values 


Record Number 

Primary File 

Secondary File 

1 

A 

B 

2 

C 

D2 

3 

D1 

X 

4 

F 

Z 


Key to Figure 5-10 

1. The first record from the primary file is read and the matching field (A) is located. 

2. The first record from the secondary file is read and the matching field (B) is located. 

3. The contents of the matching field (A) from the first record in the primary file are 
compared with the contents of the matching field (B) from the first record in the 
secondary file. A is selected. 

4. The second record from the primary file is read and the matching field (C) is 
located. 

5. The contents of the matching field (B) from the first record in the secondary file are 
compared with the contents of the matching field (C) from the second record in the 
primary file. B is selected. 

6. The second record from the secondary file is read and the matching field (D2) is 
located. 

7. The contents of the matching field (D2) from the second record in the secondary file 
are compared with the contents of the matching field (C) from the second record in 
the primary file. C is selected. 
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Figure 5-10: Using Matching Fields to Do Multifile Processing 
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Key to Figure 5-10 (Cont.) 

8. The third record from the primary file is read and the matching field (Dl) r 
located. 

9. The contents of the matching field (D2) from the second record in the secondary file 
are compared to the contents of the matching field (Dl) from the third record in the 
primary file. Dl is selected. 

10. The fourth record from the primary file is read and the matching field (F) is 
located. 

11. The contents of the matching field (D2) from the second record in the secondary file 
are compared to the contents of the matching field (F) from the fourth record in the 
primary file. D2 is selected. 

12. The third record from the secondary file is read and the matching field (X) is 
located. 

13. The contents of the matching field (F) from the fourth record in the primary file are 
compared to the contents of the matching field (X) from the third record in the sec¬ 
ondary file. F is selected. Because the primary file is now at its end, the remaining 
records in the secondary file (X and Z) are processed in order of appearance. 
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Cycle n + 5 


ZK-1475-83 

Figure 5-10: Using Matching Fields to Do Multifile Processing (Cont.) 


When the matching fields from a primary file match one or more of the secondary files, 
RPGII sets the matching-record (MR) indicator on before detail-time calculations. You can 
use the MR indicator to condition calculation and output operations for the record just 
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selected. The indicator remains on for one complete program cycle. It is set off if the record 
selected for processing contains no matching fields. A record selected using the FORCF 
operation code causes the MR indicator to remain off for one program cycle while the fore* 
record is processed. 

RPGII processes matching records for two or more files in the following ways: 

• When a record from the primary file matches a record from the secondary file, the 
record from the primary file is processed before the record from the secondary file is 
processed. The record-identifying indicator that identifies the record type just 
selected is on at the time the record is processed. 

• When records from ascending files do not match, your program processes the record 
with the lowest matching field content first. 

• When records from descending files do not match, your program processes the record 
with the highest matching field content first. 

• A record type that has no matching field specification is processed immediately after 
the previous record is processed. In this case, the MR indicator is set off. If this record 
type is the first in the file, your program processes this record first, even when it is not 
in the primary file. 

• The matching of records makes it possible to enter data from primary records into 
their secondary records because your program processes the record from the primary 
file before matching the record from the secondary file. However, the transfer of datai 
from the secondary record to matching primary records can be done only when loo ? 
ahead fields are specified. 

In the following example, matching fields are used to combine a primary file with two sec¬ 
ondary files in ascending sequence. Record-identifying indicators are assigned in the fol¬ 
lowing way: 

• 01-Records from the primary file with matching fields 

• 02-Records from the primary file without matching fields 

• 03-Records from the first secondary file with matching fields 

• 04-Records from the first secondary file without matching fields 

• 05-Records from the second secondary file with matching fields 

• 06-Records from the second secondary file without matching fields 
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0111213 1 4 I 5 I 6 1 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FRECI99A 

IP 

AF 

80 


DISK 





FRECI99B 

IS 

F 

80 


DISK 





FRECI99C 

IS 

F 

80 


DISK 





F0UTPUT 

0 

F 

80 


DISK 





IRECI99A 

I 


01 

80 Cl 



1 

80 

TEXT 


I 






1 

2 

MATCH 

Mi 

I 


02 

80 C2 







I 

IRECI99B 


03 

80 C3 



1 

80 

TEXT 


I 






1 

80 

TEXT 


I 






1 

2 

MATCH 

Ml 

I 


04 

80 C4 







I 

IRECI99C 


05 

80 C5 



1 

80 

TEXT 


I 






1 

80 

TEXT 


I 






1 

2 

MATCH 

Ml 

I 


06 

80 C6 







I 

00UTPUT 

0 

D 


NIP 

TEXT 

80 

1 

80 

TEXT 
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Table 5-4 lists the contents of the matching fields for all three files: primary, first secon¬ 
dary, and second secondary. Field values with A after the value represent values from the 
primary file. Field values with B after the value represent values from the first secondary 
Field values with C after the value represent values from the second secondary file. 


Table 5-4: Matching Field Values 


Record 

Number 

Primary 

File 

First Secondary 
File 

Second Secondary 
File 

1 

none 

none 

IOC 

2 

none 

20B 

30C 

3 

20A 

30B 

50C 

4 

20A 

30B 

50C 

5 

40A 

60B 

none 

6 

50A 

none 

60C 

7 

none 

70B 

80C 

8 

60A 

80B 

80C 

9 

80A 

80B 

none 
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Table 5-5 lists the steps involved in processing these files and those indicators that must 
be set on for the operation to occur. 

Table 5-5: Processing Records with Matching Fields 


Step 

Record Type 

Matching Field Value 

Indicators for Processing 

1 

02 

none 

Not MR and 02 

2 

02 

none 

Not MR and 02 

3 

04 

none 

Not MR and 04 

4 

05 

10C 

Not MR and 05 

5 

01 

20A 

MR and 01 

6 

01 

20A 

MR and 01 

7 

03 

20B 

MR and 03 

8 

03 

30B 

Not MR and 03 

9 

03 

30B 

Not MR and 03 

10 

05 

30C 

Not MR and 05 

11 

01 

40A 

Not MR and 01 

12 

01 

50A 

MR and 01 

13 

02 

none 

Not MR and 02 

14 

05 

50C 

MR and 05 

15 

05 

50C 

MR and 05 

16 

06 

none 

Not MR and 06 

17 

01 

60A 

MR and 01 

18 

03 

60B 

MR and 03 

19 

04 

none 

Not MR and 04 

20 

05 

60C 

MR and 05 

21 

03 

70B 

Not MR and 03 

22 

01 

80A 

MR and 01 

23 

03 

80B 

MR and 03 

24 

03 

80B 

MR and 03 

25 

05 

80C 

MR and 05 

26 

05 

80C 

MR and 05 

27 

06 

none 

Not MR and 06 


v.. 
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5.11 Processing Files With Multiple Keys 


he following program reads one input file with three keys. It uses three different file spec¬ 
ifications to pick up the three keys. Note that the three filenames use identical fields, and 
that each filename uses a different key to point to the same file. Also note the use of the 
same fields by a data structure. 


Oil I2I3I4I5I6I7I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FIDXI01 

IP 

F 

24 

4AI 

21 

DISK 


FIDXJ01 

IS 

F 

24 

3AI 

1 

DISK 

IDXIOi 

FIDXK01 

IS 

F 

24 

2AI 

11 

DISK 

IDXI01 

FIDX03A 

0 

F 

24 



DISK 


IIDXI01 

AA 








I 


1 

3 

PN 

I 


4 

10 

PNAME 

I 


11 

12 

WH0USE 

I 


13 

17 

COLOR 

I 


18 

20 

WEIGHT 

I 

IIDXJOi 

BB 

21 

24 

QTY 

I 


1 

3 

PN 

I 


4 

10 

PNAME 

I 


11 

12 

WH0USE 

I 


13 

17 

COLOR 

I 


18 

20 

WEIGHT 

I 

IIDXK01 

CC 

21 

24 

QTY 

I 

IFIELDS 

DS 

1 

24 

FIELDS 

I 


1 

3 

PN 

I 


4 

10 

PNAME 

I 


11 

12 

WH0USE 

I 


13 

17 

COLOR 

I 


18 

20 

WEIGHT 

I 


21 

24 

QTY 


0IDX03A D NIP 

0 FIELDS 24 
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Chapter 6 

Using Printer Output Files 


If you want to create a formatted report by printing an output file, you must decide what 
the report will look like before you write your program. You must know what information 
is to be printed on each heading, detail, and total line, and where the individual fields are 
to appear. 

Designing the physical layout of your report is an important part of the work necessary to 
produce a formatted report. RPG II provides several features you can use to print certain 
information automatically and to control the printing of other information. Sections 6.1 
and 6.2 describe these features and explain how to use them. 

Printer output files cause a file to be in VAX/VMS print-file format. The default PRINT 
command causes the insertion of a form-feed character when the form nears the end of a 
page. To suppress the insertion of form-feed characters, use the NOFEED qualifier to the 
PRINT command when printing printer output files created by RPG II programs. 

6.1 Editing Output 

You can use predefined Edit codes and Edit words to format numeric data for your report. 
Edit codes and words supply additional information about the output, thus increasing your 
report’s usefulness to the end user. Section 6.1.1 describes Edit codes and explains how to 
use them. See Part II, Chapter 2 for information on Edit words. 

6.1.1 Using Edit Codes and Edit Code Modifiers 

You can specify specialized editing for numeric data by entering one of the one-character 
Edit codes in column 38 of the Output specification. Edit codes consist of (1) simple Edit 
codes (X, Y, and Z) that perform one predefined function, and (2) combined Edit codes (1, 2, 
3, 4, A, B, C, D, J, K, L, and M) that perform a combination of predefined functions. See 
Part II, Chapter 2 for information on Edit codes. 
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In most cases, using one or more Edit codes to format numeric data is sufficient. However, 
there are some cases where you might want to use an Edit code modifier to perform the 
following special formatting: 

• Replace leading zeros with asterisks. 

• Put a dollar sign immediately to the left of the leftmost character. 

See Part II, Chapter 2 for information on Edit code modifiers. 


6.1.2 Using Constants 

Constants are usually used to specify headings that describe the contents of a particular 
column. To specify a constant, enter the constant string, enclosed in apostrophes, in col¬ 
umns 45 through 70 (Constant or edit word). In the following example, SALES REPORT 
appears in character positions 24 through 35 of the printed output file: 


Type (HDTE) Edit codes , 0 No CR - 



IFetch overflow (F) 

1 X 

— 

— 


— 


11 Space 

I Y date edit 

Y 

Y 

1 A 

J 


111 Skip 

1 Z zero suppress 

Y 

N 

2 6 

K 


III 1 

1 

N 

Y 

3 C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 D 

M 

File 

III 1 1 Field 

11 End position 





name 

i 

111 1 1 name 

111 1 1 1 

III Format (PB) 
III 1 

III 1+ Constant 





01 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 

101 1 I2I3I4I5I6I7II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

##### * # # 

### — ## 




ill* 


0 35 'SALES REPORT' 
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When using constants, consider the following rules: 

• Constants can contain from 1 to 24 characters. 

• Enclose constants in apostrophes (for example, ’EMPLOYEE NAME’). The apostro¬ 
phes are not printed. 

• When Using constants, leave columns 32 through 39 and column 44 blank. 

See Part II, Chapter 2 for information on Edit words. 
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6.2 Using Special Words 

RPG II provides special words that enable you to perform the following kinds of 
formatting: 

• Printing the date 

• Printing a page number and incrementing the page number by one for each new page 

• Repeating data fields in an output record 

This section describes special words and explains how to use them. 

6.2.1 Printing the Date: UDATE, UDAY, UMONTH, UYEAR 

UDATE automatically prints the date in the format month, day, year. To put slashes (/) 
between the month, day, and year (for example, 5/17/85), specify Y in column 38 of the 
Output specification. 

The default date is the system date. To change the default date, define the logical name 
RPG$UDATE to the date you want. The format of the date is dd-mmm-yyyy. The following 
example changes the date to November 2,1985. 

$ DEFINE RPG$UDATE "2-N0V-1985 " 

You can change the UDATE output format by specifying D, I, or J in column 21 of the Con¬ 
trol specification. Specifying D changes the UDATE format to day/month/year. Specifying 
I or J changes the UDATE format to day.month.year. 
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You can use UDAY, UMONTH, and UYEAR to print each component of the date in the 
format you need, as shown in the following example: 



Type (HDTE) 

Edit codes 

t 

0 

No 

CR 

- 


1 Fetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 

1 

N 

Y 

3 

C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

IIEnd position 






name 

i 

111 1 1 name 

III Format (PB) 

III 1 






01 

111 1 1 1 

II BAB A NxxNxxNxxl 

III 1 

III 1+ Constant 

or edit 

word 

+ 

0 1 

112 13 

1 4 1 l 


1 

( 

) 

1 7 1 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

***** * * * 

*** — ** 





• ■ t ■ 

0 

H IP 







0 

UYEAR 

8 






0 


9 






0 

UMONTH 

11 






0 


12 






0 

UDAY 

14 
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In this example, the special words UYEAR, UMONTH, and UDAY in the Output specifica¬ 
tion change the date format to year-month-day. The output might look like this: 

85-05-16 

When using special words, observe the following rules: 

• You cannot specify Y in column 38 (Edit code) of the Output specification for UDAY, 
UMONTH, or UYEAR. Instead, specify a constant in columns 45 through 70 (Con¬ 
stant or edit word) to separate the day, month, and year. 

• You can use these special words in Factor 1 or 2 of the Calculation specification. 

• You cannot use these special words in the Result field of the Calculation specification. 

• You cannot use the Blank after option (column 39 of the Output specification) with 
these special words. 

6.2.2 Numbering Pages: PAGE and PAGE1 through PAGE7 

RPG II provides eight special words, PAGE and PAGE1 through PAGE7, for numbering 
pages in printed output files. RPG II automatically increments the page number by one for 
each new page. You can use more than one paging special word to number several different 
output files. 
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To use one of the paging special words, specify it as a field in the Input, Calculation, or 
Output specifications. When you use a paging special word as an input field or as the 
Result field of a calculation, you can use any Field length up to 15 digits, but you must 
specify zero Decimal positions. RPGII suppresses leading zeros and signs on output unless 
you use an Edit word, use an Edit code, or specify a packed decimal or binary data format. 

If you do not define the length of a paging special word elsewhere (for example, defining a 
field to represent the page number as a result of a calculation), the page number is output 
as a four-digit numeric field with zero decimal positions. Page numbering begins with 1. 

To change the beginning page number, enter the page number you want to use as an input 
record and name the field PAGE or use a PAGE field as the result of a calculation. Enter the 
field in columns 53 through 58 of the Input specification, as shown in the following 
example: 


0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


IINPUT AA 99 


I 

1 40PAGE 


00UTPUT 

H 2 

IP 



0 

OR 

OF 



0 



UDATE Y 

8 

0 




36 'D E P 0 S I T ' 

0 




49 ' R E P 0 R T' 

0 




68 'PAGE' 

0 



PAGE 

72 
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In this example, the contents of the field PAGE appear in character positions 69 through 
72. If the value of the field is 0032, the page numbering begins with 33, because RPG II 
adds 1 to the number. The output appears as follows: 


0 : 1 ! 2 ! 3 ! a ! 5 ! G ! 7 

123456789012345678901234567890123456789012345G78901234567890123456789012345G789 

5/1G/85 DEPOSIT REPORT PAGE 33 
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Another way to change the page number is to assign the page number you want minus one 
to a PAGE field in the Result field, as shown in the following example: 


0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


C N99 
C 


Z-ADD89 PAGE 

SET0N 99 


00UTPUT H 2 IP 
0 OR OF 

0 
0 
0 
0 
0 


UDATE Y 8 

36 'D E P 0 S I T ' 
49 ' R E P 0 R T' 

68 'PAGE' 

PAGE 72 
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The output appears as follows: 


0 ! 1 ! 2 ! 3 ! 4 ! 5 ! 6 ! 7 ! 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


5/16/85 


DEPOSIT REPORT 


PAGE 90 


In this example, Z-ADD assigns 89 to PAGE. RPG II adds 1 to this number and begins 
numbering pages with 90. The assignment occurs when indicator 99 is set off. That way, 
RPG II makes the initial page number assignment only once and not every time a record is 
read. 

You can restart page numbering at any point in the program. Use any one of these methods 
to reset the value of a PAGE field: 

• Specify the Blank after option (column 39 of the Output specification) for a PAGE field 
to reset the page number to 1 after the current record is output. 

• Use a PAGE field as the result of an operation in the Calculation specification or as an 
input field. 

• Use output indicators in the Output specification to condition the value of a PAGE 
field. When the indicator is on, the value of the page field is reset to 1 before the cur¬ 
rent record is output. You cannot use these indicators to control the printing of a 
PAGE field, because a PAGE field is always printed. 
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6.2.3 Saving Time by Repeating Data: *PLACE 

You can use the special word *PLACE to repeat data in an output record. The fields or 
constants you want to repeat must have been previously defined. Then, you can use the 
same fields or constants without having to specify their Field names (columns 32 through 
37 of the Output specification) and End positions (columns 40 through 43 of the Output 
specification). When you specify *PLACE in columns 32 through 37, RPGII repeats all the 
data between the beginning position and the highest End position for any previously 
defined field in the output record. To prevent overlapping, the End position on the same 
specification as *PLACE must be at least twice the highest End position of the group of 
fields you want to repeat. 

When using *PLACE, the following columns in the Output specification that contain 
*PLACE must be left blank: 

• Column 38 (Edit code) 

• Column 39 (Blank after) 

• Column 44 (Data format) 

• Columns 45 through 70 (Constant or edit word) 

In the following example, *PLACE specifies the following fields again: 

• LIST# 

• DESCR 

• STOCK# 

• ONHAND 

• PRICE 
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0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


F0UTI91 IP F 26 DISK 

F0UT91A OF 80 PRINTER 

I* 


I0UTI91 AA 01 

I 

I 

I 

I 


1 6 STOCK# 
7 18 DESCR 
19 2100NHAND 
22 262PRICE 


C* 


C 01 LIST# ADD 


LIST# 30 


0* 


00UT91A D NIP 

0 
0 
0 
0 
0 
0 


LIST# Z 4 
DESCR 18 
STOCK# 26 
ONHANDZ 31 
PRICE K 39 
#PLACE 79 


ZK-4419-85 


Sample output from this example might look like the following: 


1 

PARSNIPS 

OEG1PQ 

17 

$ ♦ 89 

1 

PARSNIPS 

UEG1PQ 

17 

CO 

CO 

2 

SKIM MILK- 

DAROSK 

134 

$1.70 


SKIM MILK 

DAROSK 

134 

$1.70 

3 

POTATO CHIPS 

SNK945 

1 0 0 

$1*19 

3 

POTATO CHIPS 

SNK945 

100 

$1.19 

4 

2 QRT PEPSI 

DRNK1A 

87 

$1.29 

4 

2 QRT PEPSI 

DRNK1A 

87 

$1.29 

5 

BAKED BEANS 

CANFOD 

90 

$.85 

5 

BAKED BEANS 

CANFOD 

90 

$.65 


6.3 Conditioning Output Lines 

Although you can use any type of indicator to condition output, the IP (first-page) and 
overflow indicators specifically affect output. Sections 6.3.1 and 6.3.2 describe how these 
indicators affect output. 

6.3.1 Printing Lines Before Reading the First Record: First-Page Indicator 

When you specify the IP (first-page) indicator, the indicator is set on at the start of the 
program and set off after detail-time output but before the first record is read. Therefore, 
you can use this indicator to condition those heading lines you want printed before RPGII 
processes the first record. 

You specify the IP (first-page) indicator, which is always represented by IP, in columns 24 
and 25, 27 and 28, or 30 and 31 of the Output specification. 
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The following example shows how to use the IP (first-page) indicator to print a header on 
the first page of a report: 



Type (HDTE) 

Edit codes 

/ 

0 

No 

CR 

- 



IFetch overflow (F) 

1 X 

- 

— 

— 

— 

— 



11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 



III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 



III 1 

1 

N 

Y 

3 

C 

L 



III 1 Indicators 

IBlank-after (B) 

N 

N 

4 

D 

M 


File 

III 1 1 Field 

11 End position 







name 

i 

111 1 1 name 

111 1 1 1 

III Format (PB) 
mi i 







01 

II BAB A NxxNxxNxxl 

ill i 

III 1+ Constant 

or i 

edit 

word 

+ 


0 1 

112 13 

14 15 


1 

6 


1 

? 1 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## 

####* # * 

* 

###—## 

00UTPUT 

H 

201 IP 




0 

OR 

OF 




0 



UDATE 

Y 8 


0 




43 

'SALES REPORT' 

0 



PAGE 

72 


0 




67 

'PAGE' 

0 

H 

22 IP 




0 

OR 

OF 




0 




5 

'ITEM' 

0 




23 

'DESCRIPTION' 

0 




41 

'SALES' 

0 




56 

'COST' 

0 




72 

'PROFIT' 


ZK-4420-85 


The following lines are printed on the first page: 


0 ! 1 i 2 ! 3 ! 4 ! 5 ! G ! 7 

1234567890123456789012345678901234567890123456789012345678901234567890123456789 

5/19/85 SALES REPORT PAGE 1 

ITEM DESCRIPTION SALES COST PROFIT 


You can use the IP (first-page) indicator to condition only detail-time output. If you have a 
detail line that is not conditioned by any indicators or by all negative indicators, you can 
specify NIP as an indicator to prevent the line from being output before the first input 
record is read. 
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6.3.2 Specifying Page Breaks: Overflow Indicator 

You use overflow indicators to specify when a page break should occur before certain lines 
are printed. These indicators are used primarily to condition the printing of heading lines, 
but can also be used to condition calculation operations and other types of output lines. 

You can use only overflow indicators for output files going to the printer. You define the 
indicator in columns 33 and 34 of the File Description specification. The same overflow 
indicator must be used to condition the overflow lines for that same file. If no indicator is 
specified for that file, RPGII automatically handles overflow. See Section 6.4 for informa¬ 
tion on automatic overflow. 

RPG II sets on an overflow indicator only the first time an overflow condition occurs for the 
current page. An overflow condition exists whenever one of the following circumstances 
occurs: 

• A line is printed on the overflow line. 

• A line is printed past the overflow line. 

• The overflow line is passed during a space operation. 

• The overflow line is passed during a skip operation. 

When using overflow indicators on an Output specification, observe the following rules: 

• Spacing past the overflow line sets the overflow indicator on. 

• Skipping past the overflow line to any line on the same page sets the overflow indica¬ 
tor on. 

• Skipping past the overflow line to any line on the new page does not set the overflow 
indicator on unless the skip is specified past the overflow line on the new page. 

• A skip to a new page specified on a line not conditioned by an overflow indicator sets 
the overflow indicator off before the form advances to a new page. 

• If you specify a skip to a new line and the printer is currently on that line, a skip does 
not occur. 

• When an OR line is specified for an output print record, the Space and Skip entries of 
the preceding line are used. If space and skip requirements differ from the preceding 
line, enter Space and Skip entries on the OR line. 

• An overflow indicator can appear in either line of an AND or an OR relationship. In an 
AND relationship, the overflow indicator must appear on the main specification line 
for that line to be considered an overflow line. In an OR relationship, the overflow 
indicator can be specified on either the main specification line or the OR line. How¬ 
ever, only one overflow indicator can be associated with one group of output 
indicators. 
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• If an overflow indicator is used on an AND line, the line is not an overflow line. In this 
case, the overflow indicator is treated like any other output indicator. 

• An overflow indicator cannot condition an exception line (E in column 15 of the Out¬ 
put specification), but can condition fields within the exception record. 

During a normal program cycle, RPG II checks the overflow indicator only once (immedi¬ 
ately after total-time output) to see if it is set on. The overflow routine performs the follow¬ 
ing operations: 

1. RPG II prints all total lines conditioned by an overflow indicator when the indica¬ 
tor is on. 

2. RPG II prints those heading and detail lines conditioned by an overflow indicator 
when the indicator is on. 

3. Advancement to a new page does not happen automatically. Normally, one of the 
overflow lines specifies a skip to the top of a new page. 

If the overflow indicator is on, you can fetch the overflow routine before printing any total 
or detail line by specifying F in column 16 (Fetch overflow) of the Output specification. 
Fetch overflow lets you alter the RPG II logic cycle to prevent printing detail, total, and 
exception lines on or over the perforation between pages. When you fetch the overflow rou¬ 
tine, RPG II performs the following operations: 

• When an output line specifies Fetch overflow, RPG II finds out if the overflow indica¬ 
tor for that file is on. If it is, RPG II calls the overflow routine and prints only those 
overflow lines associated with the file described on the Output specification. 

• After RPG II prints the overflow lines, it prints the line that specified the Fetch 
overflow. 

• RPG II prints any detail-time and total-time lines left for that program cycle. 

When fetching the overflow routine, observe the following rules: 

• If you want to fetch the overflow line for each record in an OR relationship, you must 
specify F in column 16 (Fetch overflow) for each line. 

• You cannot specify an overflow indicator in columns 23 through 31 on the same line 
with F in column 16 (Fetch overflow). 

To decide when to fetch the overflow routine, study all possible overflow situations and 
count lines, spaces, and skips to determine what happens when an overflow occurs. 

In the following example, the length of a page is 15 lines. The overflow line is line 12. When 
the overflow line is reached, the overflow indicator OG is set on, which conditions the head¬ 
ing line that prints the date, report title, and page number at the top of each page. 
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0 I i I 2 13 I 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


F0UTI93 IP F 
F0UT93A 0 F 
L0UT93A 


74 

80 


0G 


DISK 

LPRINTER 


15FL 120L 


I0UTI93 AA Oi 


I 

1 

5 ZIP 

I 

10 

150CEN30 

I 

16 

210CEN40 

I 

22 

270CEN50 

I 

28 

330CEN60 

I 

34 

390CEN70 

I 

40 

450CEN80 

I 

46 

47 STATE 

I 

48 

59 COUNTY 

I 

63 

74 TOWN 


00UT93A H 102 


0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


OR 


D 1 


IP 

OG 


01 


UDATE Y 


PAGE 

TOWN 

COUNTY 

STATE 

CEN80 

CEN70 

CEN60 

CEN40 

CEN40 

CEN30 


10 

47 

53 

77 

13 

26 

30 

38 

46 

54 
62 
70 

78 


'SOUTHERN NEW HAMPSHIRE' 
'TOWNS' 


ZK-4421 -85 


A sample of the output from this example might look like the following: 

0 : 1 1 2 ! 3 i 4 ! 5 ! S i 7 ! 

12345678901234567890123456789012345678901234567890123456789012345678901234567800 

12/14/85 SOUTHERN NEW HAMPSHIRE TOWNS 1 


Hampstead 

Rockingham 

NH 

3 >785 

2 >401 

1 >261 

823 

823 

775 

Kingston 

Rockinsfha m 

NH 

4 >1 1 1 

2 >882 

1 >672 

1 >002 

1 >002 

1 >017 

Litchfield 

HillsborouSh 

NH 

4 >150 

1 >420 

721 

341 

341 

286 

N e w market 

Rockingham 

NH 

4 >290 

3 >361 

3 >153 

2 >640 

2 >640 

2 >511 

A t K i n s o n 

Rockinsfham 

NH 

4 >397 

2 >291 

1 >017 

434 

434 

407 

Rye 

Rockingham 

NH 

4 >508 

4 >083 

3 >244 

1 >246 

1 >246 

1 >081 

Hollis 

Hillsborough 

NH 

4 >679 

2 >616 

1 >720 

996 

996 

879 

Pete rbo r o u 3 h 

Hillsborough 

NH 

4 >895 

3 >807 

2 >963 

2 >470 

2 >470 

2 >521 

R a y m o n d 

RockinSham 

NH 

5 >453 

3 >003 

1 >867 

1 >340 

1 >340 

1 >165 
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12/14/85 SOUTHERN NEW HAMPSHIRE TOWNS 


P1 a i s t o w 

Rockingham 

NH 

5 *809 

4 *712 

2 *915 

1 *414 

1 *414 

1 *366 

W i n d h a m 

Rockingham 

NH 

5 *884 

3 *008 

1 *317 

630 

630 

538 

Seat r o o K 

Rockingham 

NH 

5 *917 

3 *053 

2 *209 

1 *782 

1 *782 

1 *688 

Pelham 

Hillsborough 

NH 

8 *090 

5 *408 

2 *805 

979 

979 

814 

A m h e r s t 

Hillsborough 

NH 

8 *243 

4 *805 

2 *051 

1 *174 

1 *174 

1*115 

Milford 

Hillsborough 

NH 

8 *885 

8 *622 

4 *883 

3 *927 

3 *927 

4 *068 

Bedford 

Hillsborough 

NH 

9 *481 

5 *859 

3 *638 

1 *561 

1 *561 

1 *328 

H a m p t o n 

Rockingham 

NH 

10 *493 

8*011 

5 *379 

2 *137 

2 *137 

1 *507 

Exeter 

Rockingham 

NH 

1 1 *024 

8 *892 

7 *243 

5 *398 

5 *398 

4 *872 


12/14/85 SOUTHERN NEW HAMPSHIRE TOWNS 3 


Goffstown 

Hillsborough 

NH 

11*315 

9 *284 

7 *230 

4*247 

4 *247 

3 *839 

L o nd onderr v 

Rockingham 

NH 

13 *598 

5 *346 

2 *457 

1 *429 

1 *429 

1 *373 

H u d s o n 

Hillsborough 

NH 

14 *022 

10 *838 

5 *878 

3 *409 

3 *409 

2 *702 

Me rrimack 

Hillsborough 

NH 

15 *408 

8 *595 

2 *989 

1 *253 

1 *253 

1 *084 

Derry 

Rockingham 

NH 

18 *875 

11*712 

6 *987 

5 *400 

5 *400 

5 *131 

Salem 

Rockingham 

NH 

24 *124 

20 * 142 

9 *210 

3 *287 

3 *287 

2 *751 

Portsmouth 

R o c k i n 3 h a m 

NH 

26 *254 

25 *717 

28 *900 

14 *821 

14 *821 

14 *495 

Nashua 

Hillsborough 

NH 

87 *885 

55 *820 

39 *098 

32 *927 

32 *927 

31 *483 

Mancheste r 

Hillsborough 

NH 

90 *938 

87 *754 

88 *282 

77 *885 

77 *685 

78 *834 


6.4 Automatic Overflow 

When an overflow indicator is not assigned to an output file going to the printer, the com¬ 
piler assigns the first unused indicator to the file. This causes a skip to line 1 whenever an 
overflow occurs, and the overflow routine executes for this file. 

You can override the printing of overflow lines by specifying an overflow indicator on the 
File Description specification. However, do not use the same indicator to condition any out¬ 
put line. This causes continuous printing of lines, regardless of page boundaries. 
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6.5 Defining the Page Size 

The Line Counter specification allows you to alter the default format of a printed output 
file. You can use this specification to change the number of lines on a page and to change 
the overflow line. 

To define the page size, you must make the following entries in the Line Counter 
specification: 

• Columns 7 through 14 (File name) — Specify the name of the output file. This file must 
have been previously defined on the File Description specification with PRINTER in 
columns 40 through 46 (Device code) and L in column 39 (Extension). 

• Columns 15 through 17 (Form length) — Specify the number of lines printed in a page. 

• Columns 18 and 19 (FL) — If you specify an entry in columns 15 through 17 (Form 
length), you must enter FL in columns 18 and 19. This entry indicates to the compiler 
that columns 15 through 17 define the Form length. 

If you do not specify an entry for Form length, the default is 66 lines. 

To define the overflow line, you must make the following entries in the Line Counter 
specification: 

• Columns 20 through 22 (Overflow line number) — Specify the line number where an 
overflow occurs. 

• Columns 23 and 24 (OL) — If you specify an overflow line number in columns 20 
through 22, you must enter OL in columns 23 and 24. This entry indicates to the com¬ 
piler that columns 20 through 22 define the Overflow line number. 

If you do not specify an entry for the Overflow line, the default is line 60. 


6.6 Formatting Output 

You can define how your printed output file will look by specifying the number of lines to 
space or skip. Spacing is relative to the line currently being printed; therefore, use spacing 
between detail lines in a report. Skipping repositions the printer to an absolute line num¬ 
ber; therefore, specify skipping for the column headers of a report. For example, if you 
specify skip to line number 2, the output line associated with that specification will be 
printed only on the second line of each page. 
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To specify the number of lines to space, you must make the following entries in the Output 
specification: 

• Column 17 (Space before) — Specifies the number of lines to be spaced before printing 
a line. 

• Column 18 (Space after) — Specifies the number of lines to be spaced after printing a 
line. 

To specify the number of lines to skip, you must make the following entries in the Output 
specification: 

• Columns 19 and 20 (Skip before) — Specifies the line number to skip to before printing 
a line. 

• Columns 21 and 22 (Skip after) — Specifies the line number to skip to after printing a 
line. 

If you make entries in both spacing and skipping columns for the same line, RPG II for¬ 
mats the output in the following order: 

1. Skip before 

2. Space before 

3. Print the output line 

4. Skip after 

5. Space after 

You can specify entries in columns 17 through 22 (Space and Skip) for the second line in an 
OR relationship; otherwise, the preceding line specifies the entries for spacing and 
skipping. 
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The following example prints TOP on line 1, TEST LINE on line 7, PRINT TWICE FOR 
BOLDING on line 13, and the fields beginning on line 16: 



Type (HDTE) 

Edit codes 

r 

0 

No 

CR 

- 


1 Fetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


m i 

1 

N 

Y 

3 

c 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

II End position 






name 

i 

Mil l name 

111 1 1 1 

111 Format (PB) 
III 1 

III 1-)- Constant 






01 

11 BAB A NxxNxxNxx1 

or edit 

word 

+ 

0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 

|l2345678901234567890123456789012345678901234567890123456789012345678901234567890| 


## ##### # # # ###—## 


00UT92A 

0 

H 

ip 


41 

'TOP' 

0 

H 

320411 IP 




0 




44 

'TEST LINE' 

0 

H 

0 IP 




0 




30 

'PRINT TWICE FOR BOLDING' 

0 

H 

15 IP 




0 




30 

'PRINT TWICE FOR BOLDING' 

0 

D 

1 NIP 




0 



DESCR 

18 


0 



STOCK# 

26 


0 



0NHANDZ 

31 


0 



PRICE K 

39 

'$' 


ZK-4422-85 
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Sample output from this example might look like the following: 


0 ! 1 ! 2 ! 3 ! 4 ! 5 ! G ! 7 ! 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

1 TOP 

3 

4 

5 

6 

7 TEST LINE 

8 

9 

10 
1 1 
12 

13 PRINT TWICE FOR BOLDING 


14 

15 


16 

1 LB CARROTS 

0EG1M0 

47 

$ ♦ 79 

17 

6 PACK SODA 

DRNK2A 

40 

$1 ♦ 48 

18 

1 LB BUTTER 

DAROBT 

38 

$1 *59 

19 

STEAK 

METO 

o *7 

$3.15 

20 

HEAD LETTUCE 

0EG1W0 

63 

$.35 
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Chapter 7 

Using Tables 


A table is a collection of similar items arranged in a specific order. Each entry in a table 
must have the same length and the same data type (either character or numeric). In 
RPG II, you use tables to locate a specific item quickly and easily. 

There are single tables and related tables. Single tables consist of just one group of similar 
entries. When you search this type of table, the result of the operation lets you know 
whether the item you are searching for is present in the table. If the search is successful, 
that entry becomes the current entry. 

Related tables are two associated tables (like a Table of Contents) that can be entered in 
alternating format. For an example of alternating format using arrays, see Part I, Section 
8.3.4. You search the first table to find out if the entry is present. If the entry is found, 
RPG II retrieves the corresponding entry from the second table. Related tables need not 
have the same number of entries unless they are described in alternating format in the 
same Extension specification. 

If you describe a table in alternating format, the first entry from the first table is read first; 
then, the first entry from the second table is read. This alternate reading continues until 
all entries from both tables are read. Together, the corresponding entries from each table 
form one record. 

Any table can be loaded at either compile time or pre-execution time. Loading is the pro¬ 
cess by which the program assigns the data you supply to the entries in the table. 

The following characteristics help determine when a table should be loaded: 

• Its contents 

• The frequency with which its entries require changing 

• The way it is to be used 

Sections 7.1 and 7.2 describe compile-time tables and pre-execution-time tables. 
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7.1 Compile-Time Tables 

Compile-time tables are part of the source program. They are compiled with the source 
program and become a permanent part of the object program. The following example 
shows a source program and a compile-time table: 



FINPUT 

IPE 

F 

30 

DISK 



FREP0RT 

0 


40 

DISK 



E 

IINPUT 

I 

AA 

01 

TABA 10 

50 5 

1 

5 ITEM 

I 





6 

102FLD1 

I 





15 

30 FLD2 

C 01 


ITEM 

L0KUPTABA 



11 

C Nil 



SET0N 



HI 

C 11 


100 

ADD FLD1 

NEW 


62 

OREPORT 

D 


01 11 




0 



NEW 

B 20 




10001100021000310004100051000610007100081000910010 

20001200022000320004100052000610007200082000920010 

30001300023000330004100053000610007300083000930010 

40001400024000340004100054000610007400084000940010 

50001500025000350004100055000610007500085000950010 


ZK-4431-85 

One advantage of compile-time tables is that they do not need to be loaded separately each 
time the program is run. However, if you need to change any of the entries in a compile¬ 
time table, you must revise the table, and then recompile the program with the revised 
table. You can, however, make temporary changes in the table during calculations. To 
make these temporary changes permanent, you would have to output the table. See Sec¬ 
tion 7.8 for information about outputting tables. 

The data in a compile-time table must follow the source program and alternate sequence 
records, if any. 


7.2 Pre-Execution-Time Tables 


Pre-execution-time tables are not part of the object program. Rather, each table is loaded 
separately from an input data file. One advantage of pre-execution-time tables is that you 
can make frequent changes to the table without recompiling the program. 

Pre-execution-time tables are loaded before the first program cycle begins. 
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7.3 Creating Table Input Records 

Table input records are the values for the entries in a table. When creating table input 
records, observe the following rules: 

• The first entry must begin in character position 1; all entries must be contiguous, with 
no space between entries, as shown in Figure 7-1: 

record 

entry 

/ \/ \/ \/ \/ \ 

12345678901234567890123456789012345678901234567890 - table 

ZK-1471-83 

Figure 7-1: Table Input Record 

This table consists of five entries in a record, each entry being ten characters long. 

• You cannot span an entry across two records. Therefore, the length of a record is lim¬ 
ited to the device’s maximum record length. If you use related tables in alternating 
format, corresponding records cannot exceed the maximum record length. 

• Each input record must have the same number of entries except the last. This record 
can be shorter to accommodate an uneven number of entries. 

When creating compile-time table input records, observe the following rules: 

• The first record must be preceded by a record containing either double slashes (//) and 
a blank or double asterisks (**) and a blank in character positions 1 through 3. Since 
these strings are delimiters, records in a compile-time table cannot contain either of 
these three characters in positions 1 through 3. 

• The last record of the last table or array can be followed with a record containing a 
slash and an asterisk (/*) in the first two character positions. This record is optional. 

When creating table input records for related pre-execution-time and compile-time tables 
in alternating format, you must enter an entry from the first table and then follow with the 
corresponding entry from the second table. 
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If you define each entry from the first table to be one character long and each entry from 
the second table to be three characters long, your table input record might appear as in 
Figure 7-2: 


entry 

/ \ 

1 333 1 333 1 3331 333 1 

tY 

entry from second table 
entry from first table 


one record 


ZK-1474-83 

Figure 7-2: Related Tables 

In this example, each record contains five entries. Each entry consists of two related 
entries. The first entry is one character long. The second entry is three characters long. 

7.4 Defining Tables 

To define a single table, you must make the following entries in the Extension specifica¬ 
tion: 

• Columns 27 through 32 (Table name) — Specify the name of the table. Table names 
can be up to six characters long, but the first three characters must always be TAB. 

• Columns 33 through 35 (Entries per record) — Specify the number of entries in a 
record. Because tables can have one or more entries per record, calculate the maxi¬ 
mum number of entries in a record by dividing the record length by the length of an 
entry. 

• Columns 36 through 39 (Number of entries per table) — Specify the number of entries 
in the table. 

• Columns 40 through 42 (Length of entry) — Specify the length of each entry. 


7-4 Using Tables 



• Column 43 (Data format) — If the table contains numeric data, you must specify its 
format. Specify P (packed decimal format), B (binary format), or leave blank 
(overpunched decimal format). When you specify packed decimal format, make sure 
the Length of entry represents the length of the numeric data in unpacked form. 
When you specify binary format, the Length of entry you specify must indicate the 
number of bytes required to store the binary field. (Use 4 for two-byte signed binary 
numbers or 9 for four-byte signed binary numbers.) 

This column must be blank for a compile-time table. 

• Column 44 (Decimal positions) — For numeric data, specify the number of positions to 
the right of the decimal point. You must specify 0 for no Decimal positions. 

• Column 45 (Sequence) — Specify A (ascending) or D (descending) to indicate that the 
entries in a table are in the specified sequence, or leave this column blank to specify 
an unsequenced table. 

In the following example, the table name is TABLE1. There are 10 entries in the table, 
with one entry in each record. The length of each entry is 5 digits, with 2 decimal positions. 
The data type of the entry in each record is overpunched numeric by default. 

-F = Format <PB> 

I -D = Decimal positions 

II -S = Sequence (AD) 

III 

111 Alternating table or array 
Table EntEnt Lenlllname Len 
or perin of FI 11 of F 

array RecTbl EntIDII EntID 

name II I MSI I IIS 

I II I Mil I II l+— Comments—+ 


7 I 

Ii234567890i234567890123456789012345678901234567890i2345678901234567890i234567890 


# # * - * - * - **** # - **** 

E TABLEi i 10 5 2 
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From To 

file file 

name name 

I I 

E I I 


0 I i 


You can define one or two tables either individually, or as a table with an alternate table 
defined in alternating format. To define an alternate table, you must make the following 
entries for the alternate table in the same Extension specification you used to describe the 
main table: 

• Columns 46 through 51 (Table name) — Specify the name of the alternate table. Table 
names can be up to six characters long. The first three characters must be TAB. 

• Columns 52 through 54 (Length of entry) — Specify the length of each entry in the 
alternate table. 
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• Column 55 (Data format) — If the alternate table contains numeric data, you must 
specify its format. Specify P (packed decimal format), B (binary format), or leave 
blank (overpunched decimal format). When you specify packed decimal format, make 
sure the Length of entry represents the length of the numeric data in unpacked form. 
When you specify binary format, the Length of entry you specify must indicate the 
number of bytes required to store the binary field. (Use 4 for two-byte signed binary 
numbers or 9 for four-byte signed binary numbers.) 

This column must be blank for a compile-time table. 

• Column 56 (Decimal positions) — For numeric data, specify the number of positions to 
the right of the decimal point. You must specify 0 for no Decimal positions. 

• Column 57 (Sequence) — You can specify A (ascending) or D (descending) to indicate 
that the entries in a table are in the specified sequence, or leave this column blank to 
specify an unsequenced table. 

The main table’s values for Entries per table (columns 36 through 39), From file name (col¬ 
umns 11 through 18), and Entries per record (columns 33 through 35) are also used for the 
alternate table. 

In the following example, two related tables are loaded from the input file INPUT. The 
second table, TAB2, is the alternate table. 


-F = Format (PB) 

I -D = Decimal positions 

II -S = Sequence (AD) 

III 


From 

file 

name 

I 

E I 


11(Alternating table or array 
To Table EntEnt Lenlllname Len 
file or perin of Fill of F 

name array RecTbl EntIDII EntID 

I name II I MSI I IIS 

I I II I INI I 111+— Comments —+ 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


*....* * * *—*—*—***** *—**** 


E INPUT TAB! 245 0ATAB2 5 0A 


ZK-4424-85 


When defining compile-time tables, observe the following rules: 

• If the compile-time table contains numeric data, it must be in overpunched format. 
Therefore, leave column 43 (Data format) blank or leave column 55 (Data format) 
blank, if you are using related tables in alternating format. 

• The input records for compile-time tables must be in the same order in which the 
tables appear in the Extension specification. 
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To define a pre-execution-time table, make the same entries you made for a single table. 
Also, in columns 11 through 18 (From file name), enter the name of the input file that 
contains the data for the table, as shown in the following example: 


-F = Format (PB) 

-D = Decimal positions 
-S = Sequence (AD) 


I - 

II -— 

III 

11lAlternating table or array 
From To Table EntEnt Lenlllname Len 
file file or perin of Fill of F 

name name array RecTbl EntIDII EntID 

I I name II I MSI I IIS 

I I I I I I INI I III+— Comments —+ 


0I1I2I3I4I5I6I7 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


. * # 
INPUTFIL 


# #—#—#—##### 

TABLEA 10 50 5 


#—#### 
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The table input file must be defined in a File Description specification with T in column 16 
(File designation). 

When using pre-execution-time tables, observe the following rules: 

• The input file cannot contain more entries than are defined for the table. If it does, a 
run-time error occurs. 

• The input file can contain fewer entries than are defined for the table, only if you do 
not specify a sequence. When you do not specify a sequence and the table contains 
fewer entries than are defined, the remaining entries are automatically filled with 
blanks for character data or zeros for numeric data. 


7.5 Searching Tables 

The LOKUP operation code searches for an entry in a table. This operation starts with the 
first entry, and searches each element for a match with the search argument. Specifying a 
table sequence is not necessary when performing LOKUP operations for an equal match. 
However, if you specify a sequence, the table can be searched faster. To save time searching 
an unsequenced table, place the more frequently referenced entries at the beginning of the 
table. 
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To search a table for an entry, you must make the following entries in the Calculation spec¬ 
ification: 

• Columns 18 through 27 (Factor 1) — Specify a field or literal representing the entry 
you want to locate. Make sure the search argument has the same length and data 
format as the entries of the table being searched. 

• Columns 28 through 32 (Operation code) — Specify the LOKUP operation code. 

• Columns 33 through 42 (Factor 2) — Specify the name of the table to be searched. 

• Columns 54 through 59 (Resulting indicator) — Specify one or more indicators to con¬ 
dition the search and to indicate whether the search has been successful. You can use 
this indicator to condition subsequent calculation and output operations. 

In the following example, the program tries to match the search argument, ITEM, with an 
entry in the table, TAB A. If a matching entry is found, indicator 11 is set on. If no matching 
entry is found, the halt indicator, HI, is set on and the program terminates. 


23456789 


FINPUT IPE F 30 DISK 
FREPORT 0 40 DISK 
E TABA 10 50 5 
IINPUT AA 01 


I 




1 

5 ITEM 

I 




6 

102FLD1 

I 




15 

30 FLD2 

c 

01 

ITEM 

L0KUPTABA 


11 

c 

Nil 


SET0N 


HI 

c 

11 

100 

ADD FLD1 

NEW 

62 


0REP0RT D 01 11 

0 NEW B 20 

// 

10001100021000310004100051000610007100081000910010 

20001200022000320004100052000610007200082000920010 

30001300023000330004100053000610007300083000930010 

40001400024000340004100054000610007400084000940010 

50001500025000350004100055000610007500085000950010 

/» 
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In this compile-time table, there are ten entries in a record and fifty entries in a table. Each 
entry is five characters long. 


7-8 Using Tables 



When you specify a sequence (either ascending or descending), you can use resulting 
indicators (EQUAL, HIGH, and LOW) in the Calculation specification to indicate the con¬ 
dition to search for and the result of the search. You can specify one of the following search 
conditions: 

• Columns 54 and 55 (HIGH) — Nearest to but greater than value only 

• Columns 56 and 57 (LOW) — Nearest to but less than value only 

• Columns 54 and 55, and 58 and 59 (EQUAL or HIGH) — Equal or nearest to but 
greater than value 

• Columns 56 and 57, and 58 and 59 (EQUAL or LOW) — Equal or nearest to but less 
than value 

The following program searches the unsequenced table TABLE2 for the value LENGTH, 
and searches the sequenced table TABLE 1 to check for a value greater than or equal to 
COST. If both conditions are satisfied, the subroutine PROCES is called to process the 
entry. 


10 11 
1234567890123456' 

1 

78901234 

2 13 1 

5678901234567890: 

4 

L2345I 

1 5 1 

57890123456789012: 

6 1 
3456789012: 
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F 80 

80 EDISK 




FFILE2 IT 

F 80 

80 EDISK 




FINFILE IP 

F 80 

80 DISK 




E FILE! 


TABLEi 1 6 

3 2A 




E FILE2 


TABLE2 1 6 

3 0 




IINFILE AA 

11 






I 




i 32C0ST 



I 




4 60LENGTH 



I 




7 100NUMBER 



C 11 

LENGTH 

LQKUPTABLE2 


20 



C N20 11 


GOTO N0PR0C 





Q li 

COST 

L0KUPTABLE1 


26 26 



C N26 


GOTO N0PR0C 





C 


EXSR PROCES 





C 

N0PR0C 

TAG 
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You can also specify a table in the Result field to retrieve the entry that corresponds to the 
entry located in a LOKUP operation. (See the example in Section 7.6.) 
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7.6 Referencing Table Entries 

When you use a table name as an operand in an operation other than as Factor 2 or other 
than as the Result field in a LOKUP operation, the table name refers to the data retrieved 
by the last successful search. You can then use the entry as an operand in a calculation or 
modify the contents of the entry when the table name is used as the Result field in a 
calculation. 

In the following example, FLD1 is the search argument in the LOKUP operation. If the 
program can locate FLD1 in TAB1, indicator 10 is set on. Then, the result of the calcula¬ 
tion on the next line replaces the current contents of the located entry in TAB1 because the 
table entry is used as the Result field. 


Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

1 

1 

1 

1 

Result 1 
field 1 

1 1 

Decimal positions 

I Hal-F adjust (H) 

II 

11Resulting 

1(indicators 

11+ - 0 

!!><=+- Comments —+ 

1 0 1 i 1 2 1 3 1 4 1 5 1 6 1 7 ll 

1123456789012345678901234567890123456789012345678901234567890123456789012345678901 



, .#.#- 

#. 

. . 

C FLD1 

C 10 TABi 

. 

LOKUPTABi 

MULT 100 

TABi 

10 
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You can specify which entry is the current entry for related tables, and then reference the 
current entry in subsequent calculations. In the following example, FLD1 is the search 
argument in the LOKUP operation. If the program locates FLD1 in TAB1, that entry 
becomes the current entry. Then, RPG II locates the corresponding entry in TAB2 and it 
then becomes the current entry for TAB2. When you reference these entries in subsequent 
calculations, RPG II uses the current entry in both tables. 


7-10 
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Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

1 

1 

1 

1 

Result 1 
field 1 

1 1 

Decimal positions 

IHalf adjust (H) 

11 

1IResulting 

11 indicators 

11+ - 0 

!!><=+- Comments —+ 

10 1 1 1 2 1 31 41 51 6 1 7 II 

1123456789012345678901234567890123456789012345678901234567890123456789012345678901 

.... .##.#.#,...... 

..ft....*....... 


.. 

C FLD1 

L0KUPTAB1 

TAB2 

10 
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7.7 Updating Tables 

To change the contents of an entry in or add new entries to a pre-execution table, edit the 
input file that contains the table. You can also use a program to modify a table and output 
the new entries. 

The following example searches related tables in alternating format. The first table TABA 
consists of a list of numbers of items in stock. The second table TABB consists of a list of 
unit prices corresponding to the item numbers. We want to raise the unit price of each item 
by 5% and output the updated table. 


1 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

** 

***** * * * 

*** — ** 

■ ■ i i 

FMASTER 

IPE 

F 30 

DISK 


FTABLE1 

IT 

F 22 

EDISK 


FTABLE2 

0 

F 22 

DISK 


FREP0RT 

0 

F 60 

DISK 


E TABLE! 

TABLE2 TABA 2 

10 5 TABB 

6 2 

IMASTER 

AA 

01 



i 



1 

5 ITEM 

C 01 


ITEM L0KUPTABA 

TABB 

11 

C Nil 


SET0N 


HI 

C 11 


1.05 MULT TABB 

TABB 

62H 

0REP0RT 

D 

11 



0 


TABB 

20 
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The related tables TABA and TABB are pre-execution-time tables. They are loaded from 
the input table file TABLE1. In the Extension specification, the output file TABLE2 is 
automatically created. (Automatic creation means that the output file does not require an 
Output specification.) 
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When the program executes, it reads the first record from the primary input file MASTER. 
ITEM is the search argument. If the search argument is matched, indicator 11 is set on and 
the corresponding entry from TABB is made available for processing. If no match is found, 
the halt indicator HI is set on and the program terminates without creating the output file 
TABLE2. 

When the program ends, the tables TABA and TABB are written to file TABLE2 with the 
same number of Entries per record as the table input file TABLE 1. 


7.8 Outputting Tables 

When you specify the name of an output file in columns 19 through 26 (To file name) of the 
Extension specification, your program creates the file automatically, as shown in the 
example in Section 7.7. 

When you specify a table as a field on an Output specification, you can output only the 
entry found by the last LOKUP operation. 

In the following example, the table TABSH is read from the file TABFILE. For this exam¬ 
ple, the table is short, meaning not all 80 entries contain data. The LOKUP operation 
searches the table for the first entry containing zeros. This entry is replaced with a field 
read from the input file IFILE. The EXCPT operation code outputs the entry TABSH with 
the new data. Remember, the entry that is updated and then output by the Output specifi¬ 
cation is the entry found by the last LOKUP operation. When the last cycle occurs, the 
entire updated table will be written to the file TABFILE2. 


r 0 I 1 I 2I 3 1 4 I 5 I 6 I 7 il 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** ***** * * 
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***—** 
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DISK 
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IIFILE 
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L0KUPTABSH 

1 40ENTRY 
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Z-ADDENTRY 

TABSH 

C 01 

20 
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00FILE 

0 

E 


TABSH 

10 
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Chapter 8 

Using Arrays 


An array, like a table, is a collection of similar items arranged in a specific order. You can 
reference individual array elements by specifying an array index, or process an entire 
array by specifying the array name during calculation operations. 

You use an array instead of a table when you want to affect all the elements in the array 
with a single reference or to reference a number of separate entries at the same time. For 
example, when you want to compute a 5% sales tax for each element in an array, you use a 
single specification to perform the operation for every element. 

8.1 Types of Arrays 

Array types are differentiated at the time they are loaded. An array can be loaded at any 
one of the following times: 

• Compile time 

• Pre-execution time 

• Execution time 

Loading is the process by which the program assigns the data you specify to the elements 
in an array. 

The following characteristics determine when an array should be loaded: 

• The contents of an array 

• The frequency with which the elements in the array require changing 

• The way the array is to be used 
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8.1.1 Compile-Time Arrays 

Compile-time arrays are part of the source program; they are compiled with the source 
program and become a permanent part of the object program. One advantage of compile¬ 
time arrays is that they do not need to be loaded separately each time the program is run. 
However, if you need to change any of the entries in a compile-time array, you must revise 
the array, and then recompile the program with the revised array. You can, however, make 
temporary changes in the array during calculation operations. To make these temporary 
changes permanent, you would have to output the array and then, using the output file as 
input, recompile the program. See Section 8.8 for information about outputting arrays. 

When you use a compile-time array, the array input data must follow the source program 
and any alternate sequence (ALTSEQ) records. If you use more than one array, the data for 
each array must follow in the same sequence as is specified on the Extension specifications. 
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The following example shows a source program with the input data for two compile-time 
arrays and their alternate compile-time arrays: 
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8.1.2 Pre-Execution-Time Arrays 

Pre-execution-time arrays are not part of the object program. Rather, each array is loaded 
separately (before the first program cycle begins) and is used like an input data file. One 
advantage of pre-execution-time arrays is that you can make frequent changes to the 
array without recompiling the program. 

8.1.3 Execution-Time Arrays 

Execution-time arrays are created by using Input or Calculation specifications. These 
arrays are loaded either from input data or as the result of calculation operations after 
program execution begins. 


8.2 Creating Array Input Records 

When creating array input records for compile-time and pre-execution-time arrays, 
observe the following rules: 

• The first entry must begin in character position 1; all entries must be contiguous, with 
no space between entries, as shown in Figure 8—1: 

entry 

/ \ 

12345678901234567890123456789012345678901234567890 - array 
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Figure 8-1: Array Input Record 

This array can be defined to consist of five entries. Each entry is ten characters long. 

• Each array input record must have the same number of entries except the last. This 
record can be shorter to accommodate an uneven number of entries. 

• You cannot span an entry across two records. Therefore, the length of a record is lim¬ 
ited to the device’s maximum record length. If you use related arrays in alternating 
format, corresponding entries cannot exceed the maximum record length. 

When creating compile-time array input records, observe the following rules: 

• The first record must be preceded by a record containing either double slashes (//) and 
a blank or double asterisks (**) and a blank in character positions 1 through 3. 
Because these strings are delimiters, compile-time array records cannot contain these 
characters in positions 1 through 3. 
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• The last record of the last compile-time table or array can be followed by a record con¬ 
taining /* in the first two character positions. This must be the last record in the 
source program, if used. 

When creating array input records for related pre-execution-time and compile-time arrays 
in alternating format, you must enter an entry from the first array and then follow with 
the corresponding entry from the second array. 

If you define each entry from the first array to be one character long and each entry from 
the second array to be three characters long, your array input record might appear as in 
Figure 8-2: 

entry 

A 

12221222122212221222 - one record 

entry from second array 
entry from first array 
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Figure 8-2: Related Arrays 

In this example, each record contains five entries. Each entry consists of two related 
entries. The first entry is one character long. The second entry is three characters long. 


8.3 Defining Arrays 

To define any array, you must make the following entries in the Extension specification: 

• Columns 27 through 32 (Array name)-Specify the name of the array. You cannot use 
TAB as the first three letters of an array name. 

• Columns 36 through 39 (Number of entries per array)-Specify the number of entries 
in the array. 

• Columns 40 through 42 (Length of entry )-Specify the length of each entry. 

• Column 44 (Decimal positions)-For numeric data, specify the number of positions to 
the right of the decimal point. You must specify 0 for no decimal positions. 

You can indicate an order to the records in an array by specifying either A (ascending) or D 
(descending) in column 45 (Sequence) of the Extension specification. 
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8.3.1 Defining a Compile-Time Array 

To define a compile-time array, you must make the following entry in the Extension speci¬ 
fication in addition to the entries required for all arrays: 

• Columns 33 through 35 (Entries per record)-Arrays can have one or more entries per 
record. The length of all entries in a compile-time array cannot exceed 96 characters. 
All records, except the last, must contain the same number of entries; each entry must 
be the same length. 

The following example describes the compile-time array Al. The array has eight entries 
with four entries in each record. Each entry is a character field that is six bytes long. The 
array records are located at the end of the program. 
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8.3.2 Defining a Pre-Execution-Time Array 

To define a pre-execution-time array, you must make the following entries in the Exten¬ 
sion specification in addition to the entries required for all arrays: 

• Columns 11 through 18 (From file name)-Specify the name of the input file that con¬ 
tains the data for the array. This input file is called a table input file. It must be 
defined in a File Description specification with T in column 16 (File designation); the 
T associates the file with the array. 
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• Columns 33 through 35 (Entries per record)-Arrays can have one or more entries per 
record. The length of all entries in a pre-execution-time array cannot exceed the max¬ 
imum number of characters for the device from which the array is loaded. All records 
except the last must contain the same number of entries; each entry must be the same 
length. 

If your pre-execution-time array contains numeric data, you can indicate the data format 
by specifying P (packed decimal format) or B (binary format), or by leaving the column 
blank (overpunched decimal format). When you specify packed decimal format, make sure 
the Length of entry represents the length of the numeric data in unpacked form. When you 
specify binary format, the Length of entry you specify must indicate the number of bytes 
required to store the binary field. (Use 4 for two-byte signed binary numbers or 9 for four- 
byte signed binary numbers.) 

When using pre-execution-time arrays, observe the following rules: 

• The input file cannot contain more entries than are defined for the array. If it does, a 
run-time error occurs. 

• The input file can contain fewer entries than are defined for the array, only if you do 
not specify a sequence. When you do not specify a sequence and the array contains 
fewer entries than are defined, the remaining entries are automatically filled, either 
with blanks for alphanumeric data or with zeros for numeric data. 

8.3.3 Defining an Execution-Time Array 

To define an execution-time array, no additional entries need be made in the Extension 
specification over those that are required for all arrays. 

If you want to load an execution-time array from an input file, you must make the follow¬ 
ing entries for the array input file in its Input specification: 

• Column 43 (Data format)-When using arrays containing numeric data, indicate the 
data format by specifying P (packed decimal format) or B (binary format), or by leav¬ 
ing the entry blank (overpunched decimal format). 

• Columns 44 through 51 (Field location)-Specify the beginning and ending character 
positions of the entire array, partial array, or array element being loaded. If the data 
format is packed decimal or binary, the field location must represent the actual size of 
an array element in bytes. 

The following example shows how to use the Input specification to load an entire execu¬ 
tion-time array containing packed decimal numbers as a single field. The array, ARR, con¬ 
tains seven elements; each element is four bytes long. The execution-time array is loaded 
from the input file ARRIN as a single field in packed decimal format. 
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0 I 1 12 13 I 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


E ARR 770 

IARRIN AA 03 

I P i 280ARR 

ZK-4435-85 

You can load part of an execution-time array using one input field. The length of the field 
must be a multiple of the length of one entry. The array is loaded beginning with the first 
element and continues loading elements until it reaches the end of the input field. 


0 I 1 I 2 I 3 14 15 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


E ARR 25 1 

IARRIN AA 03 

I i 100ARR 

ZK-4436-85 

In this example, ARR contains 25 entries. Each entry is one character long. RPGII loads 
the first ten elements of the array ARR. 

8.3.4 Defining Related Arrays in Alternating Format 

You can define related arrays either individually or in alternating format. To define arrays 
in alternating format, you must make the following entries for the second (alternate) 
array in the same Extension specification you used to describe the first (main) array: 

• Columns 46 through 51 (Array name)-Specify the name of the alternate array. 

• Columns 52 through 54 (Length of entry)-Specify the length of an entry in the alter¬ 
nate array. 

• Column 55 (Data format)-You need only specify the data format for alternate pre¬ 
execution-time arrays that contain numeric data. Specify P (packed decimal format) 
or B (binary format), or leave the entry blank (overpunched decimal format). When 
you specify packed decimal format, make sure the Length of entry represents the 
length of the numeric data in unpacked form. When you specify binary format, the 
Length of entry you specify indicates the number of bytes required to store the binary 
field. (Use 4 for two-byte signed binary numbers or 9 for four-byte signed binary 
numbers.) 
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• Column 56 (Decimal positions)-For numeric data, specify the number of positions to 
the right of the decimal point. You must specify 0 for no decimal positions. 

• Column 57 (Sequence)-You can indicate the order of entries in an alternate array by 
specifying either A (ascending) or D (descending). 

The entries made in the following columns for the main array also apply to the alternate 
array: 

• Columns 11 through 18 (From file name) 

• Columns 33 through 35 (Entries per record) 

• Columns 36 through 39 (Entries in array) 

The following example describes the pre-execution-time array A1 with six entries in each 
record and 24 entries in the array. The entries for array A1 are alternated with entries for 
array Bl. A1 contains overpunched numeric data that is six digits long with no decimal 
places. Bl contains overpunched numeric data that is four digits long with two decimal 
places. Each record in the data file contains 6 entries for A1 and 6 entries for Bl. The 
arrays are loaded from the file ARRFIL. 

A sample record from ARRFIL might look like this: 


0 0 0 0 01245 0 0 0 0 0 0 21S 2 40 0 0 0 03452 0 0 0 0 0 04799 0 0 0 0 0 057777 0 0 0 0 0 G S 5 50 
\ . /\ /\ /\ / ♦ ♦ ♦ 


t t t t 

A 1 11 Bl >1 A1 »2 Bl »2 


-F = Format (PB) 

I -D = Decimal positions 






II -S 

III 

= Sequence (AD) 





■ 11 

11lAlternating table or array 
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file 

file 
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of F 


name 

name 
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1 

1 
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1 

1 
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0 
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1 1 
890123456/ 

1 

'8901234 

2 1 
•56789015 

3 14 1 

>3456789012345678901 

5 1 6 17 II 

123456789012345678901234567890 

*. 

., ,# 
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* 

#—#—#—##### 

#—###* 
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ARRFIL 


A1 

6 24 6 0 Bl 

4 2 
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8.4 Referencing Arrays 

With tables, you can reference only the entry retrieved by the last LOKUP operation. With 
arrays, you can refer to either an entire array or to an individual array element. One 
advantage of referring to an entire array is that a single operation can affect all the ele¬ 
ments in the array. 

You can specify an array name, a comma, and an index that is up to ten characters for 
Factor 1 or Factor 2 in a Calculation specification. You can specify an array element that is 
up to six characters for the Result field. 

You can use an entire array as Factor 1, Factor 2, or the Result field in the following opera¬ 
tions: 

• ADD 

• Z-ADD 

• SUB 

• Z-SUB 

• MULT 

• DIV 

• SQRT 

• MOVE 

• MOVEL 

• MOVEA 

• XFOOT 
•LOKUP 

• PARM 

When you specify an array name in the following calculations, RPG II repeats the opera¬ 
tion for each element in the array: 

• ADD 

• Z-ADD 

• SUB 

• Z-SUB 

• MULT 
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• SQRT 

• MOVE 

• MOVEL 

• PARM 

When using entire arrays (nonindexed) in any of the above calculations, observe the fol¬ 
lowing rules: 

• When you specify arrays with the same number of elements for Factor 1, Factor 2, and 
the Result field, RPG II performs the operation on the first element, then on the sec¬ 
ond element, and so on, until all the elements in the array have been processed. 

If the arrays do not have the same number of elements, RPG II ends the operation 
when the last element of the array with the fewest elements is processed. 

• When one Factor is a field or constant and the other Factor or Result field is an entire 
array, RPG II performs the operation once for every element in the array. 

• If the operation requires Factor 2 only and the Result field is an array, RPG II per¬ 
forms the operation once for every element in the array. 

• You must specify an array for the Result field. 

• You cannot use resulting indicators to condition calculations with arrays. 

If you use an array for the Result field and an element as one of the Factors in a calculation, 
RPG II alters the value of the element as a result of the calculation. When this occurs, 
RPG II uses the new value in all subsequent operations that reference that element. 
Suppose two numeric arrays have the data in Table 8-1: 

Table 8-1: Array Element Values 


Array Element 

Value 

ARR1,1 

4 

ARR1,2 

3 

ARR1,3 

1 

ARR1,4 

5 

ARR2,1 

2 

ARR2,2 

7 

ARR2,3 

5 

ARR2,4 

9 
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If every element of ARR1 is added to element ARR2,3 and the result is placed in ARR2, the 
elements of the resulting array are in Table 8—2: 


Table 8-2: Array Elements in Calculations 


Array Element 

Expression 

Resulting Value 

ARR2,1 

(4 + 5) 

9 

ARR2,2 

(3 + 5) 

8 

ARR2,3 

(1 + 5) 

6 

ARR2,4 

(5 + 6) 

11 


You can specify an array element in most operations that take a character or numeric field 
as Factor 1, Factor 2, or the Result field. To specify an individual array element, code the 
array name, a comma, and the index. For example, ARR,12 specifies the twelfth element of 
array ARR. You can also use a field name to represent the index. For example, if you spec¬ 
ify ARR,FLD, the index value is determined by the value of the field FLD. 

An array index, whether it be a literal or a field, must always be greater than or equal to 1 
and less than or equal to the number of elements in the array. If it is not, and you specify 
the CHECK = (BOUNDS) qualifier to the RPG command, a run-time error will occur. If 
not, and you do not specify the CHECK = (BOUNDS) qualifier to the RPG command, 
unpredictable results will occur. 

If you plan to use the same array element in a calculation for every program cycle, use a 
constant number as the index. If, however, you want to reference different array elements, 
use a field name as the index. 

When array elements are scattered throughout an input record, each field must be 
described individually on the Input specification. A field description indicates the position 
of an element in the array. In such cases, there are two ways to load the data into the array: 

• Assign a unique field name to each field of array data on the input record, and then 
code calculations to move each data field individually into the appropriate array 
element. 

• Assign the array name with the proper index to each field of array data in the input 
record. The array is loaded automatically as the data is read. 
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The following example shows you how to load each element of an execution-time array 
individually: 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


E ARR 770 

IARRIN AA 03 

1 40ARR,1 
5 80ARR,2 

9 120ARR,3 
13 160ARR,4 

17 200ARR,5 
21 240ARR,6 
25 280ARR,7 

ZK-4438-85 


In the following example, a company employs eight salespeople whose weekly sales 
amounts are recorded in an input file. Each record of the file contains the weekly sales 
amounts; one new record is recorded in the file each week. At the end of the year, the com¬ 
pany likes to have a report listing the sales totals for each week and the grand total for the 
entire year. 


0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

123456789012345678901234567890123456789012345678901234567890123456789012345678901 

FINPUT1 

IPE 

F 

60 

DISK 



FREP0RT 

0 

F 

60 

DISK 



E 



WEEK 

8 6 2 



E 



YEAR 

8 8 2 



IINPUTl 

AA 

01 





I 




1 

482WEEK 


C 01 



XF00TUEEK 

TOTAL 

82 


C 01 


WEEK 

ADD YEAR 

YEAR 



CLR 



XF00TYEAR 

GRAND 

102 


0REP0RT 

D 


'01 




0 




20 'WEEKLY TQTAL=' 


0 



TOTAL 

35 '$ 

/ 

/ ■ 


0 

T 


LR 




0 




20 'YEARLY T0TAL=' 


0 



GRAND 

35 '$ 

/ / • 



ZK-4439-85 
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Two execution-time arrays, WEEK and YEAR, are defined in the Extension specification. 
The Input specification tells the program to load the array WEEK after reading each sales 
record from the input file INPUT 1. 

The input file for the execution-time array is not like a table input file with a correspond¬ 
ing File Description specification. Therefore, data is not automatically loaded into the 
array at the beginning of execution. Instead, you must describe the input data to be loaded 
into the array on Input specifications. 

The array elements are in consecutive positions in the input record. Therefore, when the 
name of the array is specified as the field name, the data is automatically loaded into the 
appropriate elements of the array as the input record is read. In this case, only one Input 
specification is necessary to describe an input record of array data. 

The XFOOT operation calculates the sum of all the elements in the array WEEK and puts 
the sum in the Result field TOTAL. The next calculation adds one array to the other. 
Adding arrays involves adding each element of one array to the corresponding element of 
the other array. Normally, when you use an array name in a calculation, the operation is 
performed on each element of the array; then, an array of the results is created. Therefore, 
you cannot use resulting indicators to indicate the result of the operation. 

These arrays have the same number of elements; therefore, any specified operation is per¬ 
formed until all elements have been processed. In the case of two arrays containing differ¬ 
ent numbers of elements, the specified operation would be performed only until the last 
element in the shorter array was processed. 

In the following example, the program produces results identical to those of the previous 
example. However, here the array elements are scattered throughout the input record. 
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FINPUT2 

IPE F 

60 

DISK 


FREPORT 

0 

F 

60 

DISK 


E 



WEEK 

8 6 2 


E 



YEAR 

8 8 2 


IINPUT 

AA 

01 




I 




1 

62WEEK,1 

I 




8 

132WEEK,2 

I 




15 

202WEEK,3 

I 




22 

272WEEK,4 

I 




29 

342WEEK,5 

I 




36 

4i2WEEK,6 

I 




43 

482WEEK,7 

I 




50 

552UEEK,8 

C 01 



XF00TWEEK 

TOTAL 

82 

C 01 


WEEK 

ADD YEAR 

YEAR 


CLR 



XF00TYEAR 

GRAND 

102 

0REP0RT 

D 


01 



0 




20 'WEEKLY T0TAL= 

0 



TOTAL 

35 '$ 

/ 

I • 

0 

T 


LR 



0 




20 'YEARLY TOTAL* 

0 



GRAND 

35 '$ 

r t ■ 


ZK-4440-85 


8.5 Searching Arrays 

The LOKUP operation code can search for an element in an array. To determine whether a 
particular element exists, you specify a search argument and define the conditions under 
which the LOKUP operation will succeed. You must also use a resulting indicator that 
specifies the condition and that will indicate the result of the LOKUP operation. The indi¬ 
cator is set on only if the search is successful; otherwise, the indicator is set off. When 
searching for a HIGH or LOW condition, you must specify a sequence for the array in col¬ 
umn 45 (Sequence) of the Extension specification. Enter an indicator in these columns to 
test for the following conditions: 

• Columns 58 and 59 (EQUAL)-Equal 

• Columns 54 and 55 (HIGH)-Nearest to but greater than value 

• Columns 56 and 57 (LOW)-Nearest to but less than value 

• Columns 54 and 55, and 58 and 59 (EQUAL or HIGH)-Equal or nearest to but greater 
than value 

• Columns 56 and 57, and 58 and 59 (EQUAL or LOW)-Equal or nearest to but less 
than value 
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If you specify both EQUAL and HIGH or EQUAL and LOW, the EQUAL condition takes 
precedence if entries satisfy both conditions. 

To search an array for an element, you must make the following entries in the Calculation 
specification: 

• Columns 18 through 27 (Factor 1)-Specify a field, literal, array element, or table rep¬ 
resenting the element you want to locate. Make sure the search argument has the 
same length and data format as the elements in the array being searched. 

• Columns 28 through 32 (Operation code)-Specify the LOKUP operation code. 

• Columns 33 through 42 (Factor 2)-Specify the name of the array to be searched. 

• Columns 54 through 59 (Resulting indicator)-Specify one or more indicators to test 
for a condition and to indicate whether the search has been successful. You can use 
these indicators to condition subsequent calculation and output operations. 

In the following example, the program tries to match the search argument QTY with an 
entry in the array ARR. If a matching entry is found, indicator 11 is set on. If the entry is 
not found, indicator 11 is set off. 


Field length 


Control level 


i 

Decimal positions 

i 


1 

IHalf adjust (H) 

1 Indicators 

Operation 

i 

ii 

1 1 

i 

i 

11 Resulting 

1 1 Factor 

1 Factor 

Result 1 

1(indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

I 1 

1 1 

!!><=+- Comments —+ 

0 1112 

1 3 1 

4 1 

5 1 6 1 7 1 

|i 2345678901234567890123456789012345678901234567890i23456789012345678901234567890| 


*« * 

# 

* * 

# 

#-### # # # 


C 01 

QTY 

L0KUPARR 


li 
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If you want to start searching an array at some point other than at the beginning, specify 
the array and its index where you want to begin the search. The index can be a literal or a 
field name. In the following example, the search begins with the seventh element of array 
ARR: 


Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

1 

1 

1 

1 

Result 1 
field 1 

1 1 

Decimal positions 

IHalf adjust (H) 

II 

11 Resulting 

11 indicators 

11+ - 0 

ll> < = +- Comments —+ 

10 11 1 2 1 3 1 4 1 5 1 6 17 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # * 

# # 

# #- 

-### # # # 

C 01 QTY 

L0KUPARR,7 


11 
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If you want to reference the element found in the last LOKUP operation, specify the array 
name and an index field in Factor 2 of the LOKUP operation. If the search is successful, the 
index value of the array element that satisfied the condition is stored in the index field and 
the resulting indicator is set on. If the search is unsuccessful, the value 1 is placed in the 
index field and the resulting indicator is set off. If you do not specify the index field, a suc¬ 
cessful LOKUP operation indicates whether an element contains the data for which you 
are searching, but does not return the element’s index value. 

If you want to begin the search with the first element, you must initialize the index field to 
1 before the LOKUP operation. 

You can also search for more than one array element by locating all the elements in an 
array that satisfy a certain condition. When the condition is satisfied, the program adds 1 
to the value in the index field to continue the search with the next element. 

In the following example: 

• The program loads a pre-execution-time array from the file INPUT1. 

• The search argument SEARCH contains the value of 50000; the LOKUP operation 
searches for any array element containing a value lower than the search argument. 

• If the search is successful, indicator 56 is set on. This indicator causes the EXCPT 
operation to print the contents of each array element (with its index) that satisfies the 
search condition. 

• After the program prints the array element, it sets indicator 56 off and adds 1 to the 
field containing the array index. As long as the index field remains below 11, the 
search continues by setting indicator 54 on; this causes the program to loop back to 
line 01090. This process continues until all 10 elements are searched. 
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i 0 I 1 I 2I 3 I 4I 5 I 6 I 7 n 
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An example of the output file might appear as follows: 


0 { 1 ! 2 ! 3 ! 4 ! 5 ! G ! 7 

12345878901234507890123458789012345878901234587890123456789012345678901234567890 


IN D E X = 0 8 
IN D E X = 0 7 
I N D E X = 0 8 
I N D E X = 0 9 
I N D E X = 10 


0 A L U E = 4 0 0 0 0 
0 A L U E = 3 0 0 0 0 
0 A L U E = 2 0 0 0 0 
0ALUE=10000 
U A L U E = 0 0 0 0 0 


The column numbers in this example are for reference and do not appear in the output. 


8.6 Moving Array Data 

You can use the MOVEA operation code to move: 

• Contiguous array elements to a field 

• A field or literal to contiguous array elements 

• Contiguous elements of one array to contiguous elements of another array 
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If the array is not indexed, data movement starts with the first element of an array or field. 
If the array is indexed, the move starts with the element you specify. Data movement stops 
when either of the following conditions is met: 

• The last array element is moved or filled. 

• The number of characters moved equals the length of the shorter field, as specified 
either in columns 33 through 42 (Factor 2) or in columns 43 through 48 (Result field) 
of the Calculation specification. 

See Part II, Chapter 3 for more information on the MOVE A operation code. 

The following example shows a pre-execution-time array ARR20 being loaded from the file 
ARRFILE. A copy of ARR20 is moved into the execution-time array ARR15 using the 
MOVEA operation code. 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FARRFILE IT F 
E ARRFILE 
E 
C 


80 EDISK 

ARR20 5 50 4 

ARR15 50 4 
M0VEAARR20 ARR15 
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8.7 Updating Arrays 

To change the contents of an element in a compile-time array, or to add new elements to 
such an array, edit the source program containing the array data, and then recompile the 
program. 

To change the contents of an element in a pre-execution-time array, or to add new elements 
to such an array, edit the table input file that contains the array. 

You can make temporary changes in arrays during program execution by using the array 
name as a Result field. You can make these temporary changes permanent by writing the 
array to an output file that you can use later as an input file. 

The following example describes the array COSTL, which is made up of six-digit 
overpunched numeric data with two decimal places. This array is read from the file 
ARRAYIN. During program execution, changes can be made to this array. At the comple¬ 
tion of the program the array will be written to the output file ARRAYOUT. The format in 
which it is written is the same as that in which it was read; that is, eight entries in each 
record with each entry being a six-digit overpunched numeric with two decimal positions. 
The files ARRAYIN and ARRAYOUT must also be described on File Description specifica¬ 
tions as an input table file (ARRAYIN) and an output file (ARRAYOUT). 
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8.8 Outputting Arrays 

You can output either an entire array or individual array elements. To output entire 
arrays, you can make entries either in an Extension specification or in an Output 
specification. 

To write a compile-time or pre-execution-time array using an Extension specification, you 
must make the following entry: 

• Columns 19 through 26 (To file name)-Specify the name of a sequential output file. 
This file must have been previously defined in a File Description specification. The 
program automatically writes the compile-time or pre-execution-time array you spec¬ 
ified in the Extension specification to this output file after reaching the end of the 
program. 

To write a compile-time, pre-execution-time, or execution-time array using an Output 
specification, you must make the following entries: 

• Columns 32 through 37 (Field name)-Specify the name of the array you want to write. 
The array is written every time the program processes a record unless you specify 
indicators in columns 23 through 31 of the Output specification. 

• Columns 40 through 43 (End position)-Specify the character position where the last 
entry of the array ends. 
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In the following example, for each record read from FILEA, the execution-time array 
DISCNT is written out to the file FILEB using Output specifications: 


E COSTLIST PRICE 5 10 5 2 

E DISCNT 10 5 2 

IFILEA AA 01 

I 1 22PERCNT 

C 01 PRICE MULT PERCNT DISCNT 
OFILEB D 1 01 

0 60 'COST WITH DISCOUNT OF ' 

0 PERCNT3 72 

0 74 '%' 

0 D 1 01 

0 DISCNT 120 ' $0. ' 
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To output an individual array element, specify the array and the index of the desired ele¬ 
ment (in the form ARR,n where n is either a constant or a field name) in columns 32 
through 37 (Field name). 

The following example outputs only the first and second element of the array DSCT: 


E COSTLIST 

PRICE 5 10 

5 2 


E 

IFILEA 

AA 

01 

DSCT 10 
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I 




1 22PERCNT 

C 01 
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MULT PERCNT 
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OFILEB 
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20 'ITEM 1 
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DSCT,1 

32 ' $0. 

i 

0 




50 'ITEM 2 
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62 ' $0. 

r 
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If you want to output numeric array elements, you can use Edit codes or Edit words to add 
commas or dollar signs, or to suppress leading zeros. Do not use Edit codes or Edit words to 
modify array data if you are going to use the data as input to subsequent programs. 

When you specify an Edit code with an entire array (nonindexed), RPG II automatically 
inserts two spaces between elements of the array in the output record. 
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Chapter 9 

Calling System Routines from VAX RPGII 


9.1 Introduction 

This chapter describes the use of RPG II operation codes to access VAX/VMS Run-Time 
Library (RTL) procedures, VAX/VMS system services, utilities (such as FMS and TDMS), 
and subprograms written in languages other than RPG II. You can access these routines by 
using the following RPG II operation codes: 

• The CALL operation code, which invokes the routine. 

• The PLIST operation code, which defines the parameter list, if used. 

• The PARM, PARMD, and PARMV operation codes, which determine the parameter 
passing mechanism. 

• The GIVNG operation code, which receives a function value or return status. 

See Part II, Chapter 3 for more information on these operation codes. 

Although calling RTL procedures, system services, and subprograms can provide many 
advantages, keep the following suggestions in mind: 

• Do not call these routines if you can perform the same task using RPG II. 

• Do not mix RTL and RPG II output routines. 

• If an RTL procedure and a system service perform the same task, use the RTL 
procedure. 

System routines are prewritten subroutines and functions provided by VAX/VMS. Each 
system routine has an entry point (the routine or service name) and an argument list. It 
may also return a function value or condition value to the program that calls it. 

System routines perform common tasks, such as finding the square root of a number or 
allocating virtual memory. If you use system routines, you will not have to rewrite code 
every time you want to perform a common task. Using system routines allows you to con¬ 
centrate on application specific tasks, not utility tasks. Some system routines even help 
independent parts of programs to allocate resources cooperatively. 
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A system routine can be called from any VAX language providing that language supports 
the data structures required by the particular routine. The results of a system routine will 
be the same, no matter what language you use. 

The system routines that are most commonly called from user programs are Run-Time 
Library routines and system services. These system routines are documented in the 
VAX/VMS Run-Time Library Routines Reference Manual and the VAX/VMS System 
Services Reference Manual. 

9.1.1 Run-Time Library Routines 

Run-Time Library routines are grouped in facilities that represent specific types of com¬ 
mon tasks. These facilities and the types of tasks they perform are shown in Table 9-1. 

Table 9-1: Run-Time Library Facilities 


Facility Types of Tasks the Routines Perform 


LIB$ General purpose procedures. Obtain records from devices, manipulate strings, con¬ 

vert data types for I/O, allocate resources, obtain the system date or time, signal 
exceptions, establish condition handlers, enable detection of hardware exceptions, 
and process cross-reference data. 

MTH$ Mathematics procedures. Perform arithmetic, algebraic, and trigonometric calcu¬ 

lations. 

OTS$ Language-independent support procedures. Perform tasks such as data type con¬ 

versions as part of a compiler’s generated code. 

SMG$ Screen management procedures. Assist you in designing, composing, and keeping 

track of complex images on a video screen; provide terminal-independent tasks. 

STR$ String manipulation procedures. Perform tasks such as searching for substrings, 

concatenating strings, and prefixing and appending strings. 


9.1.2 System Service Routines 

System service routines perform various tasks, such as controlling processes, communicat¬ 
ing among processes, and coordinating I/O. 

Unlike Run-Time Library routines which are divided into facilities, all system services 
share the same facility prefix (SYS$). However, these services are logically divided into 
groups of services which perform similar tasks. Table 9-2 describes these groups. 
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Table 9-2: Groups of System Services 


Group 

AST 

Change Mode 
Condition Handling 
Event Flag 

Information 

Input/Output 
Lock Management 
Logical Names 

Memory Management 

Process Control 

Security 

Timer and Time 
Conversion 


Types of Tasks the Services Perform 

Allow processes to control the handling of ASTs. 

Change the access mode of particular routines. 

Designate condition handlers for special purposes. 

Clear, set, read, and wait for event flags, and associate with event flag 
clusters. 

Return information about the system, queues, jobs, processes, locks, 
and devices. 

Perform I/O directly, without going through VAX RMS. 

Enable processes to coordinate access to shareable system resources. 

Provide methods of accessing and maintaining pairs of character 
string logical names and equivalence names. 

Increase or decrease available virtual memory, control paging and 
swapping, and create and access shareable files of code or data. 

Create, delete, and control execution of processes. 

Enhance the security of VAX/VMS systems. 

Schedule events, obtain and format binary time values. 


9.2 Calling System Routines from VAX RPGII 

There are seven steps required to call any system routine. 

1. Determine the type of call (procedure or function). 

2. Declare the arguments. 

3. Declare the system routine. 

4. Include symbol definitions (if applicable). 

5. Call the routine or service. 

6. Check the condition value (if applicable). 

7. Locate the result. 

As an example, you can follow these steps in writing a program to call LIB$STAT_TIMER. 
LIB$STAT_TIMER returns to its caller one of five statistics: (1) elapsed time, (2) CPU 
time, (3) buffered I/O count, (4) direct I/O count, or (5) page fault count. 
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9.2.1 Determine the Type of Call (Procedure or Function) 

Before you can set up a call to a system routine, you must determine whether the call to the 
routine or service should be a procedure call or a function call. 

A system routine must be called as a function if: 

• it returns a function value, or 

• it returns a condition value. 


NOTE 

To call a system routine as a function in RPG II, you must use the GIVNG 
opcode. A system routine should be called as a procedure only if it does not 
return a function value or a condition value. 


Although it is possible to call most of the system routines as procedures, it is recommended 
that you do so only when the text in the RETURNS section says: 

RETURNS 

None 


You may call a system routine as a procedure if you are not interested in the condition code. 
However, this is highly discouraged because not checking the condition code can lead to 
many undiscovered errors. (Checking condition values is described in Section 9.2.6.) 

To determine whether a routine returns a function value or a condition value, look at the 
description provided in the RETURNS section of the system routine description. For 
example, the RETURNS section of the LIB$STAT_TIMER documentation contains the 
following description: 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


If this text appears in the RETURNS section, the system routine returns a condition value 
and must be called as a function. In routines which return function values, the function 
value is described in the RETURNS section. 


Because LIB$STAT_TIMER does return condition values, you must call it as a function. 
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9.2.2 Declare the Arguments 

Most system routines have one or more arguments. These arguments are used to pass 
information to the system routine and to obtain information from the system routine. 
Arguments can be required or optional. 

For example, consider the arguments for the Run-Time Library routine 
LIB$STAT_TIMER. This routine had three arguments: two are required and one is 
optional. You can tell which arguments are required by looking at the FORMAT section in 
the documentation of the system routine. In the case of LIB$STAT_TIMER, the format is: 

LIB$STAT_TIMER code ,value [,handle-adr] 

The handle-adr argument appears in brackets ([ ]) indicating that it is an optional argu¬ 
ment. Only optional arguments to a system routine appear in brackets in that routine’s 
FORMAT section. For this example, you only want to use the two required arguments, so 
you need declare only the first two arguments. 

To declare an argument for a system routine, first look at that argument’s description. The 
argument description provided for the code argument is as follows: 

code 

VMS Usage: function_code 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Code specifies the statistic to be returned. The code argument contains the address of a 
signed longword integer that is this code. It must be an integer from one to five. 

Next, look at the VMS Usage entry, function_code. Table 9-3 lists the VAX RPG II 
equivalent for each of the VMS Usages. You can declare the argument using the code pro¬ 
vided in Table 9-3. 

When your program passes a parameter by reference, the parameter list contains the 
address of the location that contains the value of the parameter. Most languages pass sca¬ 
lar data by reference. 

When passing a parameter by reference, you may specify an access type and a data type in 
columns 54 through 57 of the Calculation specification for numeric data. Character data is 
always passed as a fixed-length string. Numeric data, by default, is passed as a packed 
decimal string. See Sections 9.2.2.2 and 9.2.2.3 for information on access type and data 
type. 
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In the following example, the parameter contained in the field CODE is passed by 
reference. 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

)l NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments 


01 i 121-314 I- 516171 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # # # # # #—### # # # 
C PARM CODE 90 RL 


ZK-4630-85 


The procedure used in declaring an argument is also used in declaring the value argu¬ 
ment. First, check the description of the value argument. 


value 


VMS Usage: 
type: 
access: 
mechanism: 


varying_arg 
unspecified 
write only 
by reference 


The value argument contains the address of a longword or quadword, and that is the statis¬ 
tic returned by LIB$STAT_TIMER. All statistics are longword integers except elapsed 
time, which is a quadword. 


The VMS Usage varying_arg indicates that the data type returned by the routine is 
dependent on other factors. In this case, the data type returned is dependent on the statis¬ 
tic you want to return. For this example, the statistic that you want to return is code 5, 
page fault count. This statistic is returned in a signed longword integer. Therefore, you 
need to check Table 9-3 to find the VAX RPG II statements that are used to declare a 
longword_signed. 
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Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

1 

1 

1 

1 

Result 1 
field 1 

1 1 

Decimal positions 

IHalf adjust (H) 

11 

11 Resulting 

11 indicators 

11+ - 0 

11> < = +- Comments —+ 

1011121314151617 11 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

*# # # 

# # 

# #- 

—### # # # 

c 

PARM 

CODE 

90 RL 

c 

PARM 

VALUE 

90 WL 


ZK-4631-85 

Regardless of which Run-Time Library routine or system service you are calling, the decla¬ 
ration statements for the arguments can be found by looking up the VMS Usage in Table 
9-3. 


Table 9-3: VMS Data Structures 


VMS Data Structure 

VAX RPG II Implementation 

access_bit_names 

NA 

access_mode 

Declare as text string of one byte. When using this data struc¬ 
ture, you must interpret the ASCII contents of the string to 
determine the access_mode. 

address 

L 1 

address_range 

Q 1 

arg_list 

NA 

ast_procedure 

L 1 

Boolean 

NA 

byte_signed 

Declare as text string of one byte. When using this data struc¬ 
ture, you must interpret the ASCII contents of the string. 

byte_unsigned 

Same as for byte_signed. 1 

channel 

W 1 

char_string 

TEXT STRING 

complex_number 

DATA STRUCTURE 


1 Technically, RPG II does not support unsigned data structures. However, unsigned information may be passed 
using the signed equivalent as long as the contents do not exceed the range of the signed data structure. 


(continued on next page) 


Calling System Routines from VAX RPG II 9-7 






Table 9-3: VMS Data Structures (Cont.) 


VMS Data Structure 

VAX RPG II Implementation 

cond_value 

condvalue GIVNG OPCODE 

Columns 43 through 58 

context 

L 1 

date_time 

Q 1 

device_name 

TEXT STRING 

ef_cluster_name 

TEXT STRING 

ef_number 

L 1 

exitJhandlerJblock 

DATA STRUCTURE 

fab 

Implicitly generated by the compiler on your behalf. It is not pos¬ 
sible for a user to access the fab data structure from an RPG II 
program. 

file_protection 

W 1 

floating_point 

F or D 

Column 55 

function_code 

F 

io_status_block 

Q 

item_list_2 

DATA STRUCTURE 

item_list_3 

DATA STRUCTURE 

item_quota_list 

NA 

lock_id 

L 1 

lock_status_block 

DATA STRUCTURE 

lock_value_block 

DATA STRUCTURE 

logical_name 

TEXT STRING 

longword_signed 

L 

longword_unsigned 

L 1 

mask_byte 

NA 

mask_longword 

L 1 

mask_quadword 

Q 1 

mas k__ word 

W 1 


1 Technically, RPG II does not support unsigned data structures. However, unsigned information may be passed 
using the signed equivalent as long as the contents do not exceed the range of the signed data structure. 


(continued on next page) 
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Table 9-3: VMS Data Structures (Cont.) 


VMS Data Structure 

VAX RPG II Implementation 

null_arg 

NA 

oetaword_signed 

DATA STRUCTURE 

octaword_unsigned 

DATA STRUCTURE 

page_protection 

L 1 

procedure 

L 1 

processed 

L 1 

process_name 

TEXT STRING 

quadword_signed 

Q 

quadword_unsigned 

Q 1 

rights_holder 

Q 1 

rights_id 

L 1 

rab 

NA 

sectioned 

Q 1 

section_name 

TEXT STRING 

system_access_id 

Q 1 

time_name 

TEXT STRING 

uic 

L 1 

user_arg 

L 1 

varying_arg 

Dependent upon application. 

vector_byte_signed 

ARRAY OF CHARACTER STRING 

vector_byte_unsigned 

ARRAY OF CHARACTER STRING 1 

vector_longword_signed 

ARRAY OF LONGWORD INTEGER (SIGNED) L 

vector_longword_unsigned 

ARRAY OF LONGWORD INTEGER L 1 

vector_quadword_signed 

NA 

vector_quadword_unsigned 

NA 

vector_word_signed 

ARRAY OF WORD INTEGER (SIGNED) W 

vector_word_unsigned 

ARRAY OF WORD INTEGER W 1 

word_signed 

W 

word_unsigned 

W 1 


1 Technically, RPG II does not support unsigned data structures. However, unsigned information may be passed 
using the signed equivalent as long as the contents do not exceed the range of the signed data structure. 
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9.2.2.1 Parameter Passing Mechanisms 

This section describes conventions for passing arguments in RPGII programs. 

A calling program can pass a parameter in one of three ways: 

• By value 

The PARMV operation code passes a parameter by value. 

• By reference 

The PARM operation code passes a parameter by reference. 

• By descriptor 

The PARMD operation code passes a parameter by descriptor. 

When your program passes a parameter by value, the parameter list contains the actual, 
uninterpreted 32-bit value of the parameter. 

In the following example, the constant 0 is passed by value. 


Field length 


Control level 


1 

Decimal positions 

1 


1 

IHalf adjust (H) 

1 Indicators 

Operation 

1 

1 

II 

1 1 

1 

11 Resulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # # 

c 

# # 

PARMV 

# #- 

0 

-### # # # 


ZK-4632-85 

When your program passes a parameter by reference, the parameter list contains the 
address of the location that contains the value of the parameter. Most languages pass sca¬ 
lar data by reference. 

When passing a parameter by reference, you may specify an access type and a data type in 
columns 54 through 57 of the Calculation specification for numeric data. Character data is 
always passed as a fixed-length string. Numeric data, by default, is passed as a packed 
decimal string. 
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In the following example, the parameter contained in the field TIMLEN is passed by 
reference. 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

)l NxxNxxNxxl 

1 1 

1 1 

1l> < = +- Comments — 


0 I i 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # # # # # #— ### # # # 

C PARM TIMLEN 90 UL 


ZK-4633-85 

When your program passes a parameter by descriptor, the parameter list entry contains 
the address of a descriptor for the parameter. 

In the following example, the field TIMBUF containing the parameter (fixed-length 
string) is passed by descriptor. 


Field length 


Control level 

1 


1 

1 

Decimal positions 

IHalf adjust (H) 

1 Indicators 

1 1 

Operation 

1 

1 

1 

11 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

0 I 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## * # 

# # 

# # 

—### # # * 

c 

PARMD 

TIMBUF 

23 


ZK-4634-85 
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9.2.2.2 Parameter Access Types (column 54) 

The parameter access type indicates the actions that the RTL procedure is permitted to 
perform on the parameter. Access types that you can use in RPGII are: 

• Read-only-R 

The parameter can only be read. 

• Write-only-W 

The parameter can only be written. 

• Modify-M 

The parameter can be modified (read and written). 

You can specify only the parameter access type and data type of a parameter with the 
PARM operation code. If you specify a parameter access type, you must also specify its data 
type. 

In the following example, the TIMLEN field is a longword integer (column 55) with write- 
only access (column 54). 


Field length 


Control level 


1 

Decimal positions 

1 


1 

IHalf adjust (H) 

1 Indicators 

1 1 

Operation 

1 

1 

1 

II 

1IResulting 

1 1 Factor 

1 F actor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

[Oil I2I3I4I516I7II 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # # 

# # 

* #- 

—### # # # 

c 

PARM 

TIMLEN 

90 UL 


ZK-4635-85 


9.2.2.3 Parameter Data Types (column 55-57) 

If you specify a parameter access type, you must also specify its data type. When a program 
passes a parameter to an RTL procedure, the RTL procedure expects the parameter to be of 
a particular data type. The parameter data types that can be passed from an RPG II pro¬ 
gram are: 

• Word integer (signed)-W 

• Longword integer (signed)-L 

• Quadword integer (signed)-Q 

• F_floating single-precision-F 
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• D_floating double precision-D 

• Numeric string, right overpunched sign-NRO 

• Packed decimal string (default data type for numeric data) 

• Character string (default data type for character data) 

Define the parameter data type in columns 55 through 57 of the Calculation specification. 
You can specify a data type only for numeric fields passed by reference. 

In the following example, the data type of the numeric field TIMLEN is a right 
overpunched sign. 


Field length 


Control level 

1 


1 

1 

Decimal positions 

IHalf adjust (H) 

1 Indicators 

Operation 

1 

11 

1 1 

1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

*# # * 

« * 

# #- 

-### # # * 

c 

PARM 

TIMLEN 

MNR0 
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Calling System Routines from VAX RPGII 


9-13 






9.2.3 Declare the System Routine 

Declare a system routine in your program as you declare any other external routine. The 
declaration statement will vary depending on whether the system routine is being called 
as a procedure or function. 

The routine declaration statement for calling LIB$STAT_TIMER as a function should 
appear as follows: 


Field length 


Control 

level 


1 

Decimal positions 

1 




1 

IHalf adjust (H) 

11 

1 

Indicators 

Operation 

1 

1 

1 

1 


1 

1IResulting 

1 

1 

Factor 

1 Factor 

Result 1 

11 indicators 

1 

1 

1 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

[Oil 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

* 

# 

# # 

# * 

--#*# # # # 

c 


STATIM 

EXTRN'LIB$STAT. 

-TIMER' 


c 



CALL STATIM 



c 



PARM 

CODE 

90 RL 

c 



PARM 

VALUE 

90 UL 

c 



GIVNG 

RETVAL 
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The routine declaration statement for calling LIB$STAT_TIMER as a procedure should 
appear as follows: 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

)l NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments — 


0 I i 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # # # # # #---### # * # 


C 

C 

c 

c 


STATIM EXTRN'LIB$STAT_TIMER' 

CALL STATIM 

PARM CODE 90 RL 

PARM VALUE 90 UL 


ZK-4639-85 
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9.2.4 Include Symbol Definitions 

Many system routines depend on values that are defined in separate symbol definition 
files. For example, when you call any Run-Time Library routine in the SMG$ facility, you 
must include SMGDEF. 

For Run-Time Library routines, you need to include symbol definitions such as when you 
are calling an SMG$ routine, or when you are calling a routine that is a jacket to a system 
service. (A jacket routine in the Run-Time Library is a routine that provides a simpler, 
more easily used interface to a system service.) 

All system services, however, require that you include SSDEF to check status. Many other 
system services require other symbol definitions as well. To determine whether or not you 
need to include other symbol definitions for the system service you wish to call, refer to the 
documentation for that service. If the documentation states that values are defined in the 
XXXXX macro, you must include those symbol definitions in your program. 

In VAX RPGII a definition macro is included as follows: 

$ CREATE SMGDEF♦MAR 

♦TITLE SMGDEF - Define SMG$ constants 
$SMGDEF GLOBAL 
♦ END 

$MACRO SMGDEF 

$LINK RPGPROG jSMGDEF 

As you can see from the documentation for LIB$STAT_TIMER, it does not use any 
included definition files, so this step is not applicable for this example. 

9.2.5 Call the Routine or Service 

The call to the routine or service is set up as an external call in VAX RPG II. The syntax of 
the call statement will depend on whether the call is a function call or a procedure call. 

9.2.5.1 Calling a System Routine in a Function Call 

In this example, LIB$STAT_TIMER returns a condition value called ret_status. To call a 
system routine, set up the function call in the same order as the FORMAT in the routine or 
service description. In this case, the format is as follows: 

LIB$STAT_TIMER code ,value [,handle-adr] 

As stated earlier, you are not using the optional handle-arg argument. In a format state¬ 
ment, an optional argument can appear in one of two ways: 

• [,optional-argument] 

• , [optional-argument] 
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If the comma appears outside of the brackets (,[optional-argument]) you must pass a zero 
by value. In the following example, the constant 0 is passed by value. 


Control level 

1 

1 Indicators 

1 1 

1 1 F actor 

1 1 i 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

Field length 

1 Decimal positions 

1 IHalf adjust (H) 

1 II 

1 II Resulting 

Result 1 11 indicators 

field 1 11+ - 0 

1 1 !!><=+- Comments —+ 

0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

#* # # 

# # 

# #—#** # # * 

c 

PARMV 

0 


ZK-4636-85 

If the comma appears inside the brackets ([,optional-argument]) you can omit the argu¬ 
ment, as long as it is the last argument(s) in the list. For example, look at the optional 
arguments of an imaginary routine, LIB$EXAMPLE_ROUTINE: 

LIB$EXAMPLE_ROUTINE argl [,arg2] [,arg3] [,arg4] 

You can omit all of the optional arguments without using a placeholder: 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

0I1I2I3I4I5I6I7I 

|12345678901234567890123456789012345678901234567890123456789012345678901234567890| 


## # # # # # #—### # # # 


C LIBEXA EXTRN'LIB$EXAMPLE_ROUTINE' 

C CALL LIBEXA 

C FARM ARGi 

C GIVNG RETSTA 
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However, if you omit an optional argument in the middle of the argument list, you must 
insert a placeholder: 


Field length 


Control 

level 


1 Decimal positions 

1 




1 IHalf adjust (H) 

1 

Indicators 

Operation 

1 11 

1 

1 


1 

1 IIResulting 

1 

1 

Factor 

1 Factor 

Result 1 II indicators 

1 

1 

i 

1 2 

field 1 11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 11> < = +- Comments —+ 

0 

1 

i 1 2 

1 3 1 

4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

* 

# 

# # 

# #--*## # # # 

c 


LIBEXA 

EXTRN'LIB$EXAMPLE_R0UTINE' 

c 



CALL LIBEXA 


c 



PARM 

ARGi 

c 



PARMV 

0 

c 



PARM 

ARG3 

c 



GIVNG 

RETSTA 
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In general, Run-Time Library routines use the format: 
[, optional-argument] 

while system services use the format: 
.[optional-argument] 
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Therefore, taking into account the optional argument (ARG2), the function call 
LIB$EXAMPLE_ROUTINE routine would appear as follows: 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

‘1 NxxNxxNxxl 

1 1 

1 1 

ll> < = +- Comments — 


Oi l I 21 314 I 5161 


12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#* # # * # * # — *#* # # * 


c 

c 

c 

c 

c 

c 


LIBEXA EXTRN'LIB$EXAMPLE-ROUTINE' 
CALL LIBEXA 
FARM ARGi 

PARM ARG2 

FARM ARG3 

GIVNG RETSTA 
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In passing the arguments to the procedure, you must declare the passing mechanism. 
When passing parameters by descriptor (using the PARMD operation code), RPGII uses: 

• An array descriptor for entire arrays 

• A scalar decimal descriptor for numeric data with positions to the right of the decimal 
point 

• A scalar descriptor for all other data types 

RPG II passes parameters using a scalar form, unless the parameter is an entire array. See 
Section 9.2.2.1 for information on parameter passing mechanisms. 

The passing mechanism required for a system routine argument is indicated in the argu¬ 
ment description. This is shown in the following description of the one-char-str argument 
to LIB$CHAR: 


one-char-str 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 


In this case, the passing mechanism required is “by descriptor.” The passing mechanisms 
allowed in system routines are those listed in the VAX Procedure Calling and Condition 
Handling Standard section of the Introduction to VAX/VMS System Routines . 
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To pass an argument using a specific passing mechanism, use the specifiers listed in Table 
9-4. 


Table 9-4: Passing Mechanisms 


Passing Mechanism Desired 

Specifier Required 

By value 

PARMV 

By reference 

PARM 

By descriptor 

PARMD 


NOTE 

Any passing mechanisms not listed in this table are unsupported in 
VAX RPGII. If a system routine requires a passing mechanism not listed in this 
table, it is not possible to call that routine directly from VAX RPG II. 


You are required to specify the passing mechanism, as shown in the following example 
where the PARM opcodes indicate that both CODE and VALUE are being passed by 
reference: 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

I Half adjust (H) 

II 

i i 

i 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 i 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

ll> < = +- Comments —+ 

0 1 i 1 2 1 3 1 4 1 5 1 6 1 7 11 

|i234567890i234567890123456789012345678901234567890i2345678901234567890i234567890| 


## * # # # # # — ### # # # 


C 

C 

C 

C 

C 


STATIM EXTRN'LIB$STATJTIMER' 

CALL STATIM 

PARM CODE 90 RL 

PARM VALUE 90 UL 

GIVNG RETSTA 
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9.2.5.2 Calling a System Routine in a Procedure Call 

If the routine or service you are calling does not return a function value or condition value, 
you may call the system routine as a procedure. The same rules apply to optional argu¬ 
ments, and you still follow the calling sequence presented in the FORMAT section. 
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One system routine that does not return a condition value or function value is the Run¬ 
Time Library routine LIB$SIGNAL. LIB$SIGNAL should always be called as a procedure, 
as shown in the following code: 


Field length 


Control level 


1 

Decimal positions 

1 



1 

IHalf adjust (H) 

1 

1 

Indicators 

1 

Operation 

1 

1 

1 

11 

1IResulting 

1 

1 Factor 

1 Factor 

Result! 

11 indicators 

1 

1 1 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

!!><=+- Comments —+ 

10 1 11 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

# # 

# # 

# #- 

— ### # # # 

c 

SIGNAL 

EXTRN'LIB$SIGNAL' 


c 


CALL SIGNAL 



c 


PARMV 

CODE 

90 
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9.2.6 Check the Condition Value 

After you call the system routine and control is returned to your program, you should 
check the condition value returned, if there is one. In general, all system routines return a 
condition value with the following exceptions: 

• The system routine returns a function value. (If the routine returns a function value 
this is described in the RETURNS section.) 

• The CONDITION VALUES RETURNED section states "None." 

• There is no CONDITION VALUES RETURNED section but rather a CONDITION 
VALUES SIGNALED section. (Success conditions are not signaled.) 

• The call to the routine was made as a procedure call. (In this case, no condition values 
are returned.) 

If any of the conditions listed above apply, there is no condition value to check. 

If there is a condition value, you must check this value to make sure that it indicates suc¬ 
cess. All success condition values are listed in the CONDITION VALUES RETURNED 
section of the system routine description. Success condition values always appear first in 
this list. 
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Many system routines return the condition value SS$_NORMAL as a success value. If this 
is the only possible success condition, you can test for its presence, as shown in the follow¬ 
ing example: 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 i 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

1l> < = +- Comments —+ 

1011121314151617 II 

|l2345678901234567890i23456789012345678901234567890123456789012345678901234567890| 


*# * * # * # *— ##* # # # 


C 

C 

C 

C 

C 

C 

C 

C 

C N01 
C 


SSNORM 

STATIM 


SSNORM 

STOP 


EXTRN'SS$_NORMAL' 
EXTRN'LIB$STAT_TIMER' 
CALL STATIM 
PARM CODE 

PARM VALUE 

GIVNG RETSTA 

COMP RETSTA 
EXTRN'LIB$STOP' 

CALL STOP 

PARMV RETSTA 


90 RL 
90 UL 


01 


90 RL 
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It is also possible to check for any success code because all success codes are odd. The fol¬ 
lowing code will continue execution if any success code is returned. The call to STATIM is 
conditioned by an indicator which will be set off if any success code is returned. 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 F actor 

1 2 

1 1 

Field length 

1 Decimal positions 

1 IHalf adjust (H) 

1 11 

1 1IResulting 

Result 1 11 indicators 

field 1 11+ - 0 

1 1 ll> < = +- Comments —+ 

0 1 

1 1 2 

1 3 1 

4 1 5 1 6 17 1 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # 

* 

# # 

# #—### # # # 

C 

STATIM 

EXTRN'LIB$STAT_ 

.TIMER' 

C 


CALL STATIM 

01 

c 


PARM 

CODE 90 RL 

c 


PARM 

VALUE 90 UL 

c 


GIVNG 

RETSTA 

c 

STOP 

EXTRN'LIB$ST0P' 

C 01 


CALL STOP 


c 


PARMV 

RETSTA 90 RL 
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When several success condition values are possible, you can continue execution on specific 
success codes. For example, the system service $SETEF returns one of two success values, 
SS$_WASSET or SS$_WASCLR. If you want to continue when the sucess code 
SS$_WASSET is returned, you can check for this condition value as follows: 


Field length 


Control level 


1 

--o - ■ 

Decimal positions 




1 

IHalf adjust (H) 

1 

Indicators 

Operation 

1 

11 

1 

1 

1 

1 

1IResulting 

1 

1 Factor 

1 Factor 

Result 1 

11 indicators 

1 

1 1 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

!!><=+- Comments —+ 

0 

1112 

L 3 1 

4 1 

5 1 6 17 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

# # 

# # 

# *- 

-### # # # 

C 

SETEF 

EXTRN'SY5$SETEF' 


C 


CALL SETEF 



C 


FARM 

EFN 

RL 

c 


GIVNG 

RETSTA 


c 

WASSET 

EXTRN'SS$_UASSET' 


c 

WASSET 

COMP RETSTA 


01 
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If indicator 01 is on, then SS$_WASSET was returned by the call. 

If the condition value returned is not a success condition, then the routine did not complete 
normally and the information it was supposed to return may be missing, incomplete, or 
incorrect. 

If the condition value returned was not a success code, you can check for a particular error 
condition, as shown in the following example: 


o i I r 2 i 3 i 4 i 5 i 6 i 7 i] 
12345678901234567890123456789012345678901234567890123456789012345678901234587890 


*# 

# 

# 

# # 

* #--### ■ 

C 



MOVE 'Input: ' 

PRMSTR 7 


C 


RMSE0F 

EXTRN'RMS$_E0F 

; 


C 


GETINP 

EXTRN'LIB$GET_ 

INPUT' 


C 



CALL GETINP 


i 

C 



PARMD 

INPSTR255 


c 



PARMD 

PRMSTR 


c 



PARM 

INPLEN 

UU 

c 



GIVNG 

RETVAL 


c 

02 

'Error' 

DSPLYTTY 



c 

02 

RMSE0F 

COMP RETVAL 


03 

c 

03 

' EOF' 

DSPLYTTY 
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9.2.7 Locate the Result 


Once you have declared the arguments, called the procedure, and checked the condition 
value, you are ready to use the result. To find out where the result is returned, look at the 
description of the system routine you are calling. 

9.2.7.1 Function Results 

If the routine is a function, the result is written into the variable in Factor 2 of the GIVNG 
opcode. 

For example, in this call to MTH$ACOS the result is written into the variable RESULT: 


01112131415)6171 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** # # # # # # — ### # # # 

C AC0S EXTRN'MTH$AC0S' 

C CALL AC0S 

C PARM COS RF 

C GIVNG RESULT 


ZK-4649-85 

This result is described in the RETURNS section of the system routine description. 

9.2.7.2 Procedure Results 

If the system routine is called as a procedure, the result is written into one or more of the 
arguments. To determine which argument holds the result, examine the “access” entry in 
the argument descriptions. If the access entry in an argument description says “write 
only” or “modify”, that argument contains output information written by the procedure. 

For example, LIB$CURRENCY returns the default system currency symbol. Looking at 
the argument descriptions, you know that the currency string is returned in the 
currency_str argument. 

currency-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

In all system routines, the output information returned by the routine or service has an 
access of “write only” or “modify”. 
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9.3 Examples of Calling Run-Time Library Routines 

The following examples demonstrate calls to system routines in VAX RPGII programs. 

You will not be able to call all Run-Time Library procedures because RPG II cannot supply 
some types of parameters, such as addresses. See the VAX/VMS Run-Time Library 
Routines Reference Manual for information on all RTL procedures and the parameters 
they require. 

The following example shows a call to the STR$UPCASE procedure to change the lower¬ 
case string to uppercase letters. This procedure requires two parameters: 1) the source 
string, and 2) the destination string. Both the source string HEAD and the destination 
string RESULT must be passed by descriptor, so the PARMD operation code is used. 

Because the name of this RTL procedure is longer than eight characters, the EXTRN oper¬ 
ation code is used to refer to STR$UPCASE as UPCASE. 


Field length 


Control 

level 


1 

Decimal positions 

1 




1 

IHalf adjust (H) 

1 

Indicators 

Operation 

1 

II 

1 

1 


1 

1 

11 Resulting 

1 

1 

Factor 

1 F actor 

Result 1 

11 indicators 

1 

1 

1 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

0 1 1 1 2 1 3 1 4 1 5 16 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

# 

# 

# # 

# #- 

--### # # # 

C 



MOVE 'rep head'HEAD 

8 

C 


UPCASE 

EXTRN'STR$UPCASE' 


c 



CALL UPCASE 



c 



PARMD 

RESULT 

8 

c 



PARMD 

HEAD 
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The following example calls the LIB$SET_SYMBOL procedure to redefine 
MY__PARAMETER, the Command Language Interpreter (CLI) symbol, to be the string 
OFF. This procedure requires two parameters to be passed by descriptor: 1) the symbol to 
be defined, and 2) the value to be given to the symbol. Line 220 moves the string OFF (the 
value to be given to the symbol) to the field SETVAL. Line 230 assigns a five-character 
name, STSYM, to this procedure name. Lines 240 and 250 assign the 12-character string 
MY_PARAMETER to the field SYMBL, the symbol to be defined. Line 260 invokes this 
procedure. Lines 270 and 280 pass the two parameters to the procedure. 


Field length 


Control level 


1 

Decimal positions 

1 



1 

IHalf adjust (H) 

1 

Indicators 

Operation 

1 

11 

1 

1 

1 

1 

1IResulting 

1 

1 Factor 

1 Factor 

Result 1 

11 indicators 

1 

1 1 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

1l> < = +- Comments —+ 

0 

1112 

1 3 1 

4 

1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

# * 

# # 

# # 

— ### # # # 

220C 


MOVE 'OFF' 

SETVAL 

3 

230C 

STSYM 

EXTRN'LIB$SET_ 

SYMBOL' 


240C 


MOVE 'METER' 

SYMBL 

12 

250C 


MOVEL'MY-PARA' 

SYMBL 


260C 


CALL STSYM 



270C 


PARMD 

SYMBL 


280C 


PARMD 

SETVAL 
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The following example calls the LIB$GET_INPUT procedure to ask the user for input 
from the terminal screen. This procedure requires three parameters: 1) the input text 
INPSTR (passed by descriptor) from the screen, 2) the prompt string PRMSTR (passed by 
descriptor) that is displayed before accepting input, and 3) the number of characters 
INPLEN (passed by reference) that are written to the input text. Also, this example sup¬ 
plies the field RETVAL to accept the return status (RMS$_EOF is the RTL symbolic con¬ 
stant representing one possible return status) of the operation. Actually, the program uses 
the EXTRN operation code to retrieve the value of the symbolic constant representing a 
return status. If the operation is unsuccessful, indicator 02 is set on and the string Error is 
displayed on the terminal screen. If the operation is unsuccessful because the file is at its 
EOF, the string EOF is displayed along with Error. 


Field length 


Control 

level 


1 

Decimal positions 

1 




1 

IHalf adjust (H) 

1 

Indicators 

Operation 

1 

II 

1 

1 


1 

1 

1IResulting 

1 

1 

Factor 

1 Factor 

Result 1 

11 indicators 

1 

1 

1 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

ll> < = +- Comments —+ 

0 

1 

1 1 2 

1 3 1 

4 

1 5 1 6 17 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

# 

# 

# * 

* * 

— *## # # # 

C 



MOVE 'Input: ' 
EXTRN'RMS$_E0F 

PRMSTR 

7 

C 


RMSE0F 

r 


c 


GETINP 

EXTRN'LIB$GET_ 

INPUT' 


c 



CALL GETINP 


02 

c 



PARMD 

INPSTR255 

c 



PARMD 

PRMSTR 


c 



PARM 

INPLEN 

m 

c 



GIVNG 

RETVAL 


c 

02 

'Error' 

DSPLYTTY 



c 

02 

RMSE0F 

COMP RETVAL 


03 

c 

03 

' EOF' 

DSPLYTTY 
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The following example executes TIME, a subroutine, that calls two procedures: 
COB$ACC_TIME and RPG$UDATE, to return the system date and time as a 12-digit 
field. The time format is hhmmssmmddyy (hours,minutes,seconds,month,day,year). Note 
that RPG will automatically call the RPG$UDATE RTL routine whenever UDATE, 
UDAY, UMONTH or UYEAR is referenced in the RPG program. 


0I1I2I3I4I5I 6I7I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FTTY D F 80 TTY 

C#++ 

C# Execute the TIME subroutine 
C#— 

C EXSR TIME 

C#++ 

C# Display the tine 

C#— 

C TIMBUF DSPLYTTY 

C#++ 

C# Set on an indicator to end the program 


c#— 





c 


SET0N 


LR 

c* 





c 

TIME 

BEGSR 



c#++ 





C* Call 

C0B$ACC_TIME to get the current time 


c#— 





c 

GTIME 

EXTRN'C0B$ACC- 

.TIME' 


c 


CALL GTIME 



c 


PARMD 

TEMPS 

8 

c* 

c 

c*++ 

C* Call 

c#— 

RPG$UDATE 

M0VELTEMP8 

to get the date 

HHMMSS 

6 

c 

GDATE 

EXTRN'RPG$UDATE' 


c 


CALL GDATE 



c 


PARM 

DAY 

2 

c 


PARM 

MMDDYY 

6 

c 


PARM 

YEAR 

2 

c* 





c 


M0VELDAY 

TEMP4 

4 

c 


MOVE YEAR 

TEMP4 


c 


MOVE TEMP4 

MMDDYY 


c* 





c 


MOVE MMDDYY 

TIMBUF 

12 

c 


M0VELHHMMSS 

TIMBUF 


c 


ENDSR 
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The information provided in this chapter is general to all system services and Run-Time 
Library routines. For specific information on these routines, refer to the following manu¬ 
als: 

• The VAX/VMS Run-Time Library Routines Reference Manual 

• The VAX/VMS System Services Reference Manual 

9.4 Examples of Calling System Services 

Most system services are used primarily by the VAX/VMS operating system on behalf of 
users. However, many system services are useful for application programming. 

The use of some system services is restricted to protect system performance and the integ¬ 
rity of user processes. The privileges and quotas assigned in the User Authorization File 
determine whether you can use a restricted system service. These privileges and quotas 
apply to every image that your process executes. 

The following example calls the SYS$ASCTIM system service to obtain the time. The time 
is converted from 64-bit system time format to an ASCII string. This service requires three 
parameters: 1) the length of the returned output string TIMLEN, passed by reference, 2) 
the character string TIMBUF, to receive the converted time passed by descriptor, and 3) 
the conversion value 0, passed by value. A conversion value of 1 causes only the hour, min¬ 
ute, second, and hundredth of second fields to be returned. A value of 0 causes the full date 
and time to be returned. Remember, the length of the returned output string must be long 
enough to accommodate the data to be returned. Because the TIMLEN parameter must be 
a longword, the access type (write-only) and data type (longword integer) are specified in 
columns 54 and 55. 

If the operation is successful, the date and time (TIMBUF) are displayed on the terminal. If 
the operation is unsuccessful, indicator 02 is set on. 
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Field length 


Control 

level 


1 

Decimal positions 

1 




1 

IHalf adjust (H) 

1 

Indicators 

Operation 

1 

1 

11 

1 

1 


1 

11 Resulting 

1 

1 

Factor 

1 Factor 

Result 1 

11 indicators 

1 

1 

i 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

1l> < = +- Comments —+ 

0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

# 

# 

# # 

# * 

--#*# # # # 

c 


ASCTIM 

EXTRN'SYS$ASCTIM' 


c 



CALL ASCTIM 


02 

c 



PARM 

TIMLEN 

UL 

c 



PARMD 

TIMBUF 

23 

c 



PARMV 

0 


c 

N02 

TIMBUF 

DSPLYTTY 
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The following example calls two system services — SYS$CRELOG and SYS$GETMSG. 
SYS$CRELOG sets on the external indicators 3 and 7 to control the opening of files in a 
RPGII program by calling SYS$CRELOG to define the logical name RPG$EXT_INDS. If 
the operation is not successful, BUFFER receives the error message which SYS$GETMSG 
returns, and the program displays the error message. 
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This example also demonstrates a method for modifying the external indicators logical. 
The effect is that subsequent program runs will have the appropriate external indicators 
turned on, depending on the value of the RPG$EXT_INDS logical. The external indicators 
in the program example below are not modified in the currently running program. See 
Part I, Chapter 4 for information on modifying the external indicators in a currently run¬ 
ning program. 


0 I 1 I 2 I 3 14 1 5 1 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FERR0R D F 80 TTY 

c#++ 

C# Call SYS$CREL0G to set on the external indicators 3 and 7. 



M0VEL'RPG$EXT_'L0GNAM 12 
MOVE 'INDS' L0GNAM 

MOVE '3,7' STRING 3 


C CREL0G EXTRN'SYS$CRELQG' 


C CALL CREL0G 99 

C PARMV 1 

C PARMD L0GNAM 

C PARMD STRING 

C PARMV 0 

C GIVNG RETVAL 

C#++ 


C# If the call was not successful, 

C# call SYSfGETMSG to get the error text 




CALL GETMSG 
PARMV 

RETVAL 

100 


PARM 

LENGTH 

90 UL 


PARMD 

BUFFER 

80 


PARMV 

0 



PARMV 

0 


GETMSG 

EXTRN'SYS$GETMSG' 



C#++ 

C# Display the error text 
C#— 

C 99 BUFFER DSPLYERR0R 
C#++ 


C# Set on an indicator to end the program 

C#— 

C SET0N LR 
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The following example calls an RTL procedure and a system service. The RTL routine 
LIB$CVT_HTB accepts as input an eight digit hexadecimal value. The program calls the 
system service SYS$GETMSG to get the error message text associated with the condition. 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


MOVE 'x value:'MESSAG 16 
M0VEL'Enter ' MESSAG 
DSPLYERR0R HEX 8 


CALL CVTHTB 
PARMV 
PARM 
PARM 

EXTRN'LIB$CVT.HTB' 


8 

HEX 

VALUE 


UL 


FERR0R D F 80 TTY 

C#++ 

C# Prompt message 
C#— 

C 
C 

C MESSAG 

C#++ 

C# Call LIB$CVT_HTB to convert to binary 
C#— 

C 
C 
C 
C 

C CVTHTB 

C#++ 

C# Call SYS$GETMSG to get the error text 
C#— 

C CALL GETMSG 

C PARMV VALUE 

C PARM LENGTH 

C PARMD BUFFER 80 

C PARMV 0 

C PARMV 0 

C GETMSG EXTRN'SYS$GETMSG' 

C#++ 

C# Display the error text 
C#— 

C BUFFER DSPLYERR0R 

C#++ 

C# Set on an indicator to end the program 
C#— 

C SET0N LR 


90 

90 UL 
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For additional information on coding considerations when using external routines, refer to 
the following manuals: 

• The Introduction to VAX/VMS System Routines 

• The Guide to Creating Modular Procedures on VAX/VMS 

Section 2 of the Introduction to VAX/VMS System Routines contains the VAX Procedure 
Calling and Condition Handling Standard. The VAX/VMS Modular Programming Stan¬ 
dard can be found in Appendix A of the Guide to Creating Modular Procedures on 
VAX/VMS. 

9.5 Examples of Calling Subprograms 

Just as they call RTL procedures and system services, RPG II programs can call sub¬ 
programs written in other languages. 

The following program calls a VAX COBOL subprogram and a VAX BASIC subprogram. 


o i l i 2 i 3 i 4 i 5 i l i i n 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # # # # # * -### # # # 


c#— 


c#++ 

C# The sane paraneter 

C#— 

C PARAM 

C 

C#++ 

C# Call the VAX COBOL 
C#~ 

C 

C 

C 

C#++ 


list is used by both calls 
PLIST 

PARM MESSAG 16 


program 

MOVEL'RPG call'MESSAG 
MOVE 'ed COBOL'MESSAG 
CALL 'COBOL!' PARAM 


C# Call the VAX BASIC program 
C#— 

C MOVE 'BASIC' MESSAG 
C CALL 'BASIC1' PARAM 
C#++ 


C# Set on an indicator to end the program 


C SET0N 


LR 


ZK-4657-85 


9-32 Calling System Routines from VAX RPG II 





The following example is the VAX COBOL subprogram. 

IDENTIFICATION DIVISION. 

PROGRAM-ID♦ COBOL 1 ♦ 

DATA DIVISION. 

LINKAGE SECTION. 

01 MESSAGE-1 PIC X(IS)♦ 

PROCEDURE DIVISION USING MESSAGE-1. 

PO. 

DISPLAY MESSAGE-1 ♦ 

EXIT PROGRAM. 

The following example is the VAX BASIC subprogram. 

100 SUB BASIC1 (STRING MESSAGE = IS BY REF) 

200 PRINT MESSAGE 
300 END SUB 


9.6 Screen Handling in VAX RPGII 

This section provides examples of RPG II program fragments that perform screen han¬ 
dling using TDMS, FMS and SMG. 

VAX TDMS (Terminal Data Management System), VAX FMS (Form Management Sys¬ 
tem), and SMG (Screen Management) are designed to make it easier to develop interactive 
applications. Both TDMS and FMS provide utilities that let you define all the screen forms 
outside the RPG II program. They also let you design forms by typing them directly onto 
the terminal screen. An example of a TDMS program is provided in 
SYS$EXAMPLES:RPGTDMS.COM. 

The following TDMS examples are part of the complete program example provided in 
SYS$EXAMPLES. 

The following example demonstrates the use of data structures and COPY from CDD in an 
RPG II program that calls TDMS. See Part II, Chapter 2 for more information on data 
structures and COPY from CDD. 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


IEMPLOY 

I i 91 EMPREC 

IEMPREC DS 

I/COPY-CDD 'EMPLOYEE-RECORD' 
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The following example demonstrates the use of long character literals in an RPG II pro¬ 
gram which calls TDMS. See Part II, Chapter 2 for more information on long character 
literals. 


Field length 


Control 

level 


1 

Decimal positions 

1 




1 

IHalf adjust (H) 

1 

Indicators 

Operation 

1 

1 

11 

1 

1 


1 

1IResulting 

1 

1 

Factor 

1 Factor 

Result 1 

11 indicators 

1 

1 

1 

1 2 

field 1 

11+ - 0 

Cl 

NxxNxxNxxl 

1 1 

1 1 

ll><=+- Comments —+ 

I 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

* 

* 

* * 

# #- 

--### # # # 

C 


REQUES 

EXTRN'TSS$REQUEST' 


C 



CALL REQUES 


99 

c 



PARM 

CHAN 

90 UL 

c 



PARM 

LIBID 

90 UL 

c 



PARMD 

II 



C" 'EMPLOYEE-INITIAL-REQUEST' 
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For further information on VAX TDMS, see the following related documents: 

• VAX TDMS Forms Manual 

• VAX TDMS Request Manual 

• VAX TDMS Application Programming Manual 

• VAX TDMS Sample Application Manual 

The following fragment is from an RPG II program that calls FMS to display a form. 


Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

II 

1 1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

10 11 1 2 1 3 1 4 1 5 1 6 1 711 

|l2345678901234567890123456789012345678901234567890123456789012345678901234567890| 


## # # # # # #—### # # # 


C 

C 

C 

C 


FCLRSH EXTRN'FDV$CLRSH' 

MOVE 'FIRST ' FORM! 6 

CALL FCLRSH 

PARMD FORM! 
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For further information on VAX FMS, see the following related document: 

• VAX FMS Reference Manual 

Following is an RPG II program calling SMG$ routines. This program displays the word 
’Menu’ beginning at line 2, column 5. 

See the VAXIVMS Run-Time Library Routines Reference Manual for information on SMG 
routines. 


Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

Result 1 
field 1 

1 1 

Decimal positions 

IHalf adjust (H) 

II 

11 Resulting 

11 indicators 

11+ - 0 

1l> < = +- Comments —+ 

0 1112 

1 3 1 

4 

1 5 1 6.1 7 1 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # * 

* * 

* * 

—### # # # 

C CREPAS 

EXTRN'SMG$CREATE_PASTEB0ARD' 

C CREDIS 

EXTRN'SMG$CREATE_VIRTUAL_DISPLAY' 

C PUTCHA 

EXTRN'SMG$PUT 

-CHARS' 


C PASDIS 

EXTRN'SMG$PASTE-VIRTUAL_DISPLAY' 

C 

Z-ADD0 

ZERO 

90 

C 

Z-ADDi 

LINC0L 

90 

C 

Z-ADD2 

LINE 

90 

C 

Z-ADD5 

COLUMN 

90 

C 

MOVE 'Menu' 

OUT 

4 

C# Create the pasteboard. 



c 

CALL CREPAS 



c 

PARM 

PASTID 

90 UL 

c 

PARMV 

ZERO 


c 

PARM 

HEIGHT 

90 WL 

c 

PARM 

WIDTH 

90 UL 

C# Create the virtual display. 



C 

CALL CREDIS 



C 

PARM 

HEIGHT 

RL 

C 

PARM 

WIDTH 

RL 

C 

PARM 

DISPID 

90 UL 

C# Output the 'Menu' 

■ 



C 

CALL PUTCHA 



C 

PARM 

DISPID 

RL 

C 

PARMD 

OUT 


C 

PARM 

LINE 

RL 

C 

PARM 

COLUMN 

RL 

C# Paste the virtual display. 



C 

CALL PASDIS 



C 

PARM 

DISPID 

RL 

C 

PARM 

PASTID 

RL 

C 

PARM 

LINCOL 

RL 

C 

PARM 

LINCOL 

RL 

C 

SET0N 


LR 
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Chapter 10 

Debugging VAX RPGII Programs 


The VAX/VMS Symbolic Debugger enables you to debug RPG II programs by monitoring 
the flow of program execution and logic. For a complete description of debugger capabili¬ 
ties, see the VAX/VMS Symbolic Debugger Reference Manual. 

The debugger lets you: 

• Set breakpoints. (Breakpoints stop program execution just before a specified line is 
executed.) 

• Set tracepoints. (Tracepoints cause the debugger to pause and display a message 
whenever a specified line is executed.) 

• Set watchpoints. (Watchpoints cause the debugger to stop and display a message 
whenever a specified variable is modified.) 

• Examine and modify source code. 

• Examine and modify data. 

• Evaluate arithmetic expressions. 

• Step through a program (Single STEP commands cause the debugger to execute one 
or more lines and then stop program execution.) 

The debugger needs information generated by both the RPG II compiler and the VAX/VMS 
Linker. Specifying the DEBUG qualifier with the RPG command creates the symbolic 
information for the debugger. Specifying the DEBUG qualifier with the LINK command 
makes the information available to the debugger. 

RPG II supports the following options at compile time for the DEBUG = options qualifier. 

• ALL 

• NONE 

• [NOJTRACEBACK 

• [NOJSYMBOLS 
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Specifying the DEBUG = SYMBOLS qualifier for the RPG command allows you to 
examine and change the contents of variables throughout your program. However, file 
names from File Description specifications are not available as variables. 

If you omit the DEBUG qualifier from the RPG and LINK commands, you can specify the 
DEBUG qualifier with the RUN command. In this case, no symbolic information is availa¬ 
ble to the debugger; you must make every reference to a program variable in terms of its 
absolute address. 

If you do not specify the DEBUG qualifier with any of the RPG, LINK, or RUN commands, 
and an error occurs, you receive a traceback list (a description of the logic flow up to the 
point where the error was detected). However, you cannot invoke the debugger. If you com¬ 
pile your program with the DEBUG = NOTRACEBACK qualifier or link your program 
with the NOTRACE qualifier, you do not receive the traceback list. The default options for 
the DEBUG qualifier are TRACEBACK and NOSYMBOLS. 

If you want to use the source line display while using the COMPILE command, you must 
inform the debugger where the source file resides. To do this, complete the following steps: 

1. Define the symbol RPG to include symbols for the VAX/VMS Symbolic Debugger 
(for example, RPG : = = RPG/DEBUG). 

2. Execute the RPG II editor COMPILE command during the editing session. 

3. Execute the LINK/DEBUG command after exiting from the editor. 

4. Execute the RUN command. 

5. Enter the debugger command: SET SOURCE source-file-spec. 

See Part I, Chapter 2 for information on compiling and linking RPG II programs and their 
respective command qualifiers. 

If you are using the VAX/VMS Performance and Coverage Analyzer, you must specify the 
following: 

/DEBUG=SYS$LIBRARY:PCA$OBJ*OBJ MYPROGRAM♦OBJ 

The VAX/VMS Performance and Coverage Analyzer consists of a collector and an ana¬ 
lyzer. The collector gathers information (such as execution counts) on your program while 
it is executing. The analyzer makes it possible to interpret the data gathered by the collec¬ 
tor. The analyzer is used to track a performance problem in a whole program down to a 
certain module, or even down to a certain line of code. See Appendix C for an example of the 
VAX/VMS Performance and Coverage Analyzer applied to an RPG II program. 
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10.1 Debugging RPGII Programs 

Debugging RPG II programs is somewhat different from debugging programs in other lan¬ 
guages. The RPG II program cycle determines the order in which the program lines are 
processed. See Part I, Chapter 1 for a complete discussion of the RPG II program cycle. 

You can reference those line numbers RPG II assigns to your program in the listing file. 
The line numbers you specify in columns 1 through 5 of a specification are not used. The 
compiler assigns line numbers only to certain specifications at specific points in the logic 
cycle; therefore, you can specify a breakpoint or tracepoint at these points in the program: 

• A break at a File Description specification occurs just before an input or update file is 
opened or just before an output file is created. The line number of this break corre¬ 
sponds to the File Description specification for this file. 

• A break at an Input specification occurs before the fields are loaded with data from a 
record. The line number of this break corresponds to the record definition in an Input 
specification. 

• You can set two breaks for each Calculation specification. The first break occurs just 
after testing control-level indicators, if used, and just before testing conditioning 
indicators. The second break occurs just before executing the operation code. For 
example, if a Calculation specification begins with line number 25, you can specify 
the line and statement number SET BREAK 25.1 to test indicators. SET BREAK 25.2 
breaks just before executing the operation code. If a particular Calculation specifica¬ 
tion has no indicators, SET BREAK 25 breaks just before executing the operation 
code. 

• A break at an Output specification occurs after the output buffer has been built but 
before the record is output. The line number of the break corresponds to the record 
definition in an Output specification. 

10.2 Debugger Commands and Keywords 

There are many debugger commands, but not all debugger commands are appropriate for 
use in debugging RPG II programs. Table 10-1 lists some debugger commands and 
keywords (and their abbreviations) that are helpful in debugging RPG II programs. 
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Table 10-1: Debugger Commands and Keywords 


Command Names Keywords 


SET (SE) 

SHOW (SH) 
CANCEL (CAN) 
EXAMINE (E) 
EVALUATE (EV) 
DEPOSIT (D) 
EXIT (EXI) 

STEP (S) 

GO (G) 

EDIT (ED) 


LANGUAGE (LA) 
MODULE (MODU) 
SCOPE (SC) 
BREAK (B) 

TRACE (T) 

WATCH (W) 


The rest of this chapter describes these debugger commands and explains how to use them. 


10.3 Preparing to Debug a Program 

This section describes the SET LANGUAGE and SHOW LANGUAGE commands. These 
commands are used to establish the proper environment for debugging an RPGII program. 

10.3.1 SET LANGUAGE and SHOW LANGUAGE Commands 

The SET LANGUAGE command causes the debugger to conduct the debugging dialog 
according to the conventions of the specified language. If your program does not call any 
subprograms written in languages other than RPG II, you do not need to use the SET LAN¬ 
GUAGE command. If your program calls a subprogram written in another language, you 
can cause the debugger to execute the subprogram by specifying the STEP/INTO com¬ 
mand. See Section 10.4.5 for information about the INTO qualifier. Once the debugger is in 
the subprogram, you must use the SET LANGUAGE command to specify the language of 
the subprogram. After you have finished executing the subprogram and you have returned 
to the main program, you must use the SET LANGUAGE command to specify the lan¬ 
guage of the main program. 

The format of the SET LANGUAGE command is: 

SET LANGUAGE language 

where: 

language Specifies the language to be used. 
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To determine the language of the program currently being executed, use the SHOW 
LAN GUAGE command. The format of the SHOW LANGUAGE command is: 

SHOW LANGUAGE 

The debugger responds by displaying the program’s language, as shown in the following 
example: 

DBOSHOH LANGUAGE 
language: RP G 


10.4 Controlling Program Execution 

To see what is happening during execution of your program, you must be able to suspend 
and resume the program at specific points. The following commands are available for these 
purposes: 

SET BREAK 
SHOW BREAK 
CANCEL BREAK 
SETTRACE 
SHOW TRACE 
CANCELTRACE 
SET WATCH 
SHOW WATCH 
CANCEL WATCH 
SHOW CALLS 
GO 
STEP 
TYPE 
CTRL/Y 
EXIT 

You can specify an RPGII label as a breakpoint or a tracepoint. These labels correspond to 
specific points in the logic cycle. The following list describes RPG II labels: 

• *DETL - Breaks just before outputting heading and detail lines 

• *GETIN - Breaks just before reading the next record from the primary or secondary 
file 

• *TOTC - Breaks just before performing total-time calculations 

• *TOTL - Breaks just before performing total-time output 

• *OFL - Breaks just before performing overflow output 

• *DETC - Breaks just before performing detail-time calculations 
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10.4.1 SET BREAK, SHOW BREAK, and CANCEL BREAK Commands 

The BREAK commands allow you to select specific locations for program suspension, so 
that you can examine or modify the following data: 

• Variables 

• Table entries 

• Array elements 

When you specify a table name, you can examine or modify the entry retrieved from the 
last LOKUP operation. 

You can also set a breakpoint at any place listed in Section 10.1. 

The BREAK commands perform the following functions: 

• SET BREAK defines the line number that will suspend execution. 

• SHOW BREAK displays all breakpoints currently set in the program. 

• CANCEL BREAK removes selected breakpoints. 

The format of the SET BREAK command is: 

SET BREAK %LINE lin-num[.stmnt-num] [DO(command(s))] 
where: 

lin-num Specifies the line number where the breakpoint will occur. You can 

also specify a logic cycle label, a TAG name, or a subroutine label. 

stmnt-num Specifies the statement number where the breakpoint will occur. 

You can use statement numbers only with Calculation specifica¬ 
tions that have conditioning indicators. 

DO(command(s)) Requests the debugger to perform the specified debugger com¬ 
mands, if specified, when the breakpoint is reached. 

In the following example, SET BREAK examines variables TOTAL and AREA when the 
breakpoint at line 100 is reached: 

DBG >SET BREAK ZLINE 100 DO(EXAM INE TOTAL ? EXAMINE AREA) 

The format of the SHOW BREAK command is: 

SHOW BREAK 
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SHOW BREAK takes no arguments. The debugger responds by displaying the current 
breakpoints, as shown in the following example: 

DBG>SET BREAK LOOP 

DBG>SET BREAK ‘/.LINE BO 

DBG>SHOW BREAK 

breaKpoint at ARRK37\L00P 

breakpoint at ARRX37VXLINE 50 

The format of the CANCEL BREAK command is: 

CANCEL BREAK %LINE lin-num[.stmnt-num] 

/ALL 


where: 

lin-num[.stmnt-num] Removes the breakpoint at the specified line and statement num¬ 
ber, logic cycle label, TAG name, or subroutine label 

/ALL Removes all breakpoints in the program 

Normally, the debugger displays the line number when it suspends execution because of a 
breakpoint or step. There are two exceptions to this behavior: 

• When stepping through a subroutine, the debugger displays the subroutine label. 

DBG>STEP 

stepped to PR0G1\SUB1 

• When stepping through a TAG, the debugger displays the TAG name. 

DBG>STEP 

stepped to PR0G1\TAG1 

10.4.2 SET TRACE, SHOW TRACE, and CANCEL TRACE Commands 

The TRACE commands let you set, examine, and remove tracepoints in your program. A 
tracepoint is similar to a breakpoint in that it suspends program execution; however, after 
displaying the trace variables, program execution resumes immediately. Thus, trace- 
points let you follow the sequence of program execution to ensure that execution is being 
carried out in the proper order. 

Tracepoints and breakpoints are mutually exclusive. If you set a tracepoint at a current 
breakpoint, the breakpoint will be canceled. If you set a breakpoint at a current tracepoint, 
the tracepoint will be canceled. 
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The TRACE commands perform the following functions: 

• SET TRACE establishes points within the program where execution is momentarily 
suspended. 

• SHOW TRACE displays the points in the program where tracepoints are currently 
set. 

• CANCEL TRACE removes one or more tracepoints currently set in the program. 

The format of the SET TRACE command is: 

SET TRACE %LINE lin-num[.stmnt-num] 
where: 

lin-num[.stmnt-num] Specifies the line and statement number, logic cycle label, TAG 
name, or subroutine label where the tracepoint will occur. 

The format of the SHOW TRACE command is: 

SHOW TRACE 

SHOW TRACE takes no arguments. The debugger responds by displaying the current 
tracepoints, as shown in the following example: 

DBG >SET TRACE L00P2 

DBG >SET TRACE /'LINE 100 

DBG>SHOW TRACE 

tracepoint at ARRX37\L00P2 

tracepoint at ARRX37\ 1 LINE 100 

The format of the CANCEL TRACE command is: 

CANCEL TRACE %LINE lin-num[.stmnt-num] 

/ALL 


where: 

lin-num[.stmnt-num] Removes the tracepoint at the specified line and statement num¬ 
ber, logic cycle label, TAG name, or subroutine label 

/ALL Removes all tracepoints in the program 


10-8 


Debugging VAX RPGII Programs 



10.4.3 SET WATCH, SHOW WATCH, and CANCEL WATCH Commands 

The WATCH commands let you monitor the contents of variables. Watchpoints determine 
when an attempt is made to modify variables. When an attempt is made, the debugger 
halts program execution, and prompts for a debugger command. Watchpoints are moni¬ 
tored continually. Thus, you can determine whether a particular variable is being modified 
inadvertently during program execution. Watchpoints, tracepoints, and breakpoints are 
mutually exclusive. The WATCH commands perform the following functions: 

• SET WATCH defines the variable(s) to be monitored. 

• SHOW WATCH displays the variable currently being monitored. 

• CANCEL WATCH disables monitoring of specified variables. 

The format of the SET WATCH command is: 

SET WATCH vbl 
where: 

vbl Specifies the variable to be monitored. You can monitor variables and array ele¬ 
ments. 

In the following example, SET WATCH sets a watchpoint for the variable AREA: 

DBG>SET WATCH AREA 

The format of the SHOW WATCH command is: 

SHOW WATCH 

SHOW WATCH takes no arguments. The debugger responds by displaying the current 
watchpoints, as shown in the following example: 

DBG>SET WATCH INDEX2 

DBOSHOW WATCH 

watchpoint of ARRX37X INDEX2 

The format of the CANCEL WATCH command is: 

CANCEL WATCH vbl 
/ALL 


where: 

vbl Specifies the variable that disables monitoring. 

/ALL Removes all watchpoints from the program. 

The following command cancels the watchpoint for the variable AREA: 

DBOCANCEL WATCH AREA 
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10.4.4 SHOW CALLS Command 


SHOW CALLS can be used to produce a traceback of calls to program modules. It is partic¬ 
ularly useful when you have returned to the debugger following a CTRL/Y command. The 
format of the SHOW CALLS command is: 

SHOW CALLS [n] 

The debugger displays a traceback list, showing the sequence of calls to program modules 
leading to the current module. 

If you include a value for n, the n most recent calls are displayed. 

10.4.5 GO and STEP Commands 

GO and STEP let you initiate and resume program execution. GO initiates execution from 
the current line or at a specified point in the program, and continues to the end of the pro¬ 
gram or to the next breakpoint. STEP initiates execution from the current line, and contin¬ 
ues for a specified number of lines. 

The format of the GO command is: 

GO [%LINE lin-num[.stmnt-num]] 

where: 

lin-num[.stmnt-num] Specifies the line and statement number, TAG name, or subrou¬ 
tine label where execution will begin. 

The normal use of GO is to continue execution after a breakpoint or at program initiation. 
Resuming execution at a point other than the current line can cause unpredictable results 
because of the nature of the RPGII logic cycle. 

Use the STEP command to execute one or more RPG II program lines and immediately 
return to the debugger. The format of the STEP command is: 

STEP [/qualifiers] [n] 

The value specified for n determines the number of statements to be executed. If you spec¬ 
ify 0, or omit a value for n, a value of 1 is assumed. 

You can specify the following qualifiers with the STEP command: 

SYSTEM Causes the debugger to count steps wherever they occur. The NOSYS- 

[NO]SYSTEM TEM qualifier is the default. 

OVER Causes the debugger to ignore calls to subprograms as it steps through 

the program. That is, to step over each call to a subprogram. The 
OVER qualifier is the default. 
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INTO 


Causes the debugger to recognize calls to subprograms as it steps 
through the program. That is, to step into each subprogram. The 
NOINTO qualifier is the default. 

LINE Causes the debugger to step through the program on a line-by-line 

basis. The LINE qualifier is the default. 

SOURCE Causes the debugger to display the line(s) of source code that corre¬ 

sponds to the line(s) being executed with each step. Source lines are 
also displayed when a breakpoint or watchpoint occurs. When step¬ 
ping through Input and Output specifications, the debugger displays 
the first line of a record definition. 

You can specify one or more qualifiers each time you issue a STEP command, or you can 
use a SET STEP command to override the defaults. 

The following command specifies that the defaults for the LINE, INTO, and SYSTEM 
qualifiers are overridden: 

DBG>SET STEP NOLINE»INTO^SYSTEM 

When you subsequently issue a STEP command with no qualifiers, the debugger assumes 
these qualifiers (NOLINE, INTO, and SYSTEM) are in effect. You can, however, supersede 
the current qualifiers by including a qualifier with a STEP command. 

The following command executes ten lines, regardless of the SET STEP command: 
DBG>STEP/LINE 10 

It is advisable to use STEP to execute only one or a few lines at a time. To execute many 
lines and then stop, use a SET BREAK command to set a breakpoint, then issue a GO 
command. 

10.4.6 TYPE Command 

The TYPE command displays the line of source code you specify. The format of the TYPE 
command is: 

TYPE [lin-num[:line-num][,...]] 
where: 

lin-num[:!in-num] Specifies the number of lines of source code to be displayed. 

The following command displays lines 1 through 30: 

DBG >TYPE 1:30 
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The following command displays lines 1 and 30: 

DBOTYPE 1 >30 

You can display the line after the current line by typing TYPE and by pressing the 
RETURN key. 

10.4.7 EDIT Command 

The EDIT command allows you to edit the file you are debugging. Before entering the 
debugger, you must define the symbol LSEDIT as follows: 

$ LSEDIT :== RPG/EDIT 

The editing session begins at the current debugging line. 

EDIT/EXIT specifies that you want to end the debugging session and begin an editing 
session. 

EDIT/NOEXIT specifies that you want to return to the debugging session after you make 
your edits. The NOEXIT qualifier is the default. 

10.4.8 CTRL/Y Command 

You can use the CTRL/Y command at any time to return to the system command level. You 
issue this command when you press the CTRL key and the Y key at the same time. The 
dollar sign ($) prompt will be displayed on the terminal. To return to the debugger, type 
DEBUG. Use the CTRL/Y command if your program goes into an infinite loop or, for some 
reason, fails to stop at a breakpoint. To find out where you were at the instant CTRL/Y was 
executed, use the SHOW CALLS command after you have returned to the debugger. 

10.4.9 EXIT Command 

The EXIT command lets you exit from the debugger when you are ready to terminate a 
debugging session. The format of the EXIT command is: 

EXIT 

EXIT takes no arguments. To return to system command level, after your program has 
terminated, use the EXIT command. 
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10.5 Examining and Modifying Locations 

Once you have set breakpoints and begun execution, the next step is to see whether correct 
values are being generated and, if necessary, to change the contents of variables as execu¬ 
tion proceeds. You may also want to calculate the value of an expression that appears in 
your program. The debugger provides the following commands for these purposes: 
EXAMINE, DEPOSIT, and EVALUATE. 

10.5.1 EXAMINE Command 

The EXAMINE command lets you look at the contents of: 

• A variable 

• The current table entry 

• An array element 

• The I/O buffer 

The format of the EXAMINE command is: 

EXAMINE vbl [,vbl] 
where: 

vbl Specifies a simple or subscripted variable. 

The following command displays the contents of the variable SALES: 

DBOEXAMINE SALES 

The following command displays the contents of the ninth element in array ARRAY: 

DBOEXAMINE ARRAY ( 9 ) 

The following command displays the contents of the first through the tenth elements of the 
array ARRAY. 

DBOEXAMINE ARRAY ( 1 : 10 ) 

You can examine indicators to see whether they are set on or off. Precede the indicator you 
want to examine with the string *IN. If an indicator is set on, 1 is displayed. If an indicator 
is set off, 0 is displayed. 

The following command displays the current setting for indicator 56: 

DBOEXAMINE *IN5G 

The debugger responds by displaying: 

* IN5S: "0" 
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You cannot examine external indicators this way, but you can do the following. To deter¬ 
mine the current value of U5, for example, enter 

DBG> CALL RPG$EXTINDS<5> 

The debugger responds by displaying: 

value r e t u r ned is 0 

The program must have been linked with the NOSEYSSHARE qualifier to do this. 

You can also display the current contents of the I/O buffer. To display the I/O buffer, specify 
the name of the input file, update file, or output file, a dollar sign ($), and the string BUF. 

The following command displays the contents of the I/O buffer for the input file INPUT: 
DBG>EXAMINE INPUT$BUF 

10.5.2 DEPOSIT Command 

The DEPOSIT command lets you change the contents of specified variables. The format of 
the DEPOSIT command is: 

DEPOSIT vbl = value 

where: 

vbl Specifies the variable that the value is deposited into, 
value Specifies the value to be deposited. 

You can change the contents of a specific variable or of several consecutive variables, as 
shown in the examples in this section. 

Values deposited into numeric fields are aligned on the decimal point. Shorter fields are 
padded with zeros to the left and right of the decimal point. 

The following command places the decimal value 100 into the variable BONUS: 

DBG>DEP0SIT B0NUS=100 

The following command places the decimal values 100, 150, and 200 into elements 1, 2, 
and 3 of array ARRAY: 

DBG>DEPOSIT ARRAY(1) = 100 * 150# 200 

The delimiters used to enclose ASCII strings in the DEPOSIT command can be either sin¬ 
gle O or double (”) quotation marks. Use the keyboard apostrophe for the single quotation 
mark. 

Values deposited into character fields are left justified. If the value contains fewer charac¬ 
ters than the character field, the field is padded on the right with spaces. 
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The following command places the string ACTIVE in the variable STATUS: 

DBG>DEPOSIT STATUS= " ACT I ME" 

You can also use DEPOSIT to set indicators on or off. Precede the indicator you want to set 
with the string *IN. To set an indicator on, specify 1 as the variable value. To set an indica¬ 
tor off, specify 0 as the variable value. 

The following command sets indicator 56 on: 

DBG>DEPOSIT *IN5G = "l" 

10.5.3 EVALUATE Command 

The EVALUATE command lets you use the debugger as a calculator to determine the 
value of arithmetic expressions. The format of the EVALUATE command is: 

EVALUATE expression 

where: 

expression Specifies the expression whose value is to be determined. 

The following command displays the value of the expression ARRAY(FLDl) * FLD2: 

DBG >EMALUATE ARRAY(FLD1) * FLD2 
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Chapter 11 

Interpreting a Compiler Listing 


This chapter explains the parts of a full compiler listing. This sample listing is for the pro¬ 
gram shown under the Source Listing title. The circled numbers on the program listing 
correspond to the following numbered text. 

1. The program name. 

2. The date and time of compilation. 

3. The name and version number of the compiler. 

4. The creation date and time of the source file. 

5. The complete file specification (device:[directory]filename.type;version) for the 
source file. The number in parentheses is a text editor page number. 

Items 1 through 5 appear at the top of each page in the listing file. 

6. The 80-column ruler. 

7. Source line numbers assigned by the compiler. The VAX/VMS Symbolic Debugger 
uses these line numbers as location specifications. 

A ‘C’ after the line number indicates that the line was generated by a copy 
directive. 

8. Source Listing — Source code. 

9. Machine Code Listing — The compiler-generated object code for the program you 
compiled. 

10. Cross Reference in Alphabetical Order — The user-defined names in alphabetical 
order and the line numbers in which they are referenced. The first column with the 
pound sign (#) after the number lists the line number where the data name is 
defined. For example, DEPQTY is defined in line 19 and referenced in lines 19, 21, 
and 22. 

DEPQTY 19# 19 21 22 
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11. Indicator Cross Reference — The indicators and the line numbers in which they are 
referenced. For example, indicator 01 is referenced in lines 12,18,19, and 36. 

01 12 18 19 36 

12. PROGRAM SECTIONS — Names the PSECT numbers and names. 

13. The bytes allocated for each PSECT 

14. The PSECT attributes. See the VAX/VMS Linker Reference Manual for informa¬ 
tion on PSECT attributes. 

15. COMMAND QUALIFIERS — Lists the command line you entered and names the 
compiler defaults that were in effect when the program was compiled. 

16. The actual CPU time it took to compile the program. 

17. The elapsed time it took to compile the program. 

18. The number of page faults. 

19. The number of virtual memory pages used to compile the program. 
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SHIPS Q 

© 

2 8 - J u n - 19 8 5 

15:58:45 

MAX RPG II M2,0 Q 

Pa Se 1 

Source Listing 

© 

28-Jun-1985 

15:58:12 

RPG$:ETSAKERES.RPG3SHIPS.RPG51 

. ( 1 ) 


© 12 3 4 5 6 7 8 

1 2345678901234567890123456789012345078901234587890123458789012345878901234567890 


1 

© 

H* + + 

H* FUNCTIONAL 

DESCRIPTION: 

3 


H* This 

pros 

raw produces a report of shipments for various 

a 


H* products 

b r o K e n 

down by division and department usin S an 

5 


H * i n p u t 

f il 

e with 

the shipment data for the past 4 quarters 

6 


H*-- 





7 


H 





8 


FSHIPS 

IP 

F 

41 

DISK 

9 


FSUMREP 

0 

F 

98 

LPRINTER 

10 


E 



QTY 4 2 0 

1 1 


LSUMREP 

55FL 

5 0 0 L 


12 


ISHIPS 

AA 

01 



13 


I 




1 5 DIM L2 

14 


I 




8 7 DEPT LI 

15 


I 




8 18 PROD 

18 


I 




17 24 QTY 

17 


C* 





18 


C 01 




XFOOTQTY PROQTY 30 

19 


C 01 


PROQTY 

ADD DEPUTY DEPUTY 30 

20 


c* 





21 


CL 1 


DEPUTY 

ADD DIMUTY DIMQTY 30 

22 


CL 1 




Z-ADDO DEPUTY 

23 


CL2 


DIMQTY 

ADD FINUTY FINQTY 40 

24 


C* 





25 


OSUMREP 

H 

001 

IP 


28 


0 




48 'PRODUCT SHIPMENT REPORT 

27 


□ 

H 

02 

IP 


28 


0 




UDATE Y 12 

29 


0 




48 ' PRODUCT SHIPMENT REPORT 

30 


0 

H 

1 

IP 


31 


0 




42 'SHIPMENTS' 

32 


Q 

H 

2 

IP 


33 


0 




15 'DIVISION DEPT' 

34 


0 




24 'PRODUCT' 

35 


0 




48 'Q1 Q2 Q3 Q4 TOTAL' 
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3S 

0 

D 1 

01 







37 

0 


L2 

DIM 

8 





38 

0 


LI 

DEPT 

14 





39 

0 



PROD 

25 





40 

0 



QTY Z 

41 





41 

0 



PROQTYZ 

48 





42 

0 

T 1 

LI 







43 

0 

T 0 

L2 







44 

0 



DIM 

89 





45 

0 

T 0 

L2 







48 

0 



DIM 

89 





47 

0 

T 02 

L2 







48 

0 



DIMQTYZB 

48 





49 

0 




83 

'<== Total for' 




50 

0 



DIM 

89 





51 

0 

T 0 

LR 







52 

0 



FINQTY1 

48 





53 

□ 




85 

'<== GRAND TOTAL' 




54 










SHIPS 






28-Jun- 1985 15:58:45 

MAX RPG II M2,0 

Pa de 

2 

Machine Code Listinsf (sj) 




28-Jun-1985 15:58:12 

R P G $:CTSAKERES.RPGISHIPS.RPG?1 ( 1 ) 




* P00000000 

.BYTE 

- X 5 3 i 

- X48 » - X49 t '' X50 » - X53 


; 

"SHIPS" 

00000008 


.BYTE 

YX53,"X55» 

-X4D» 'X 5 2» 

- X 4 5 i 

- X 5 0 

5 

"SUMREP" 


00000010 


CD 

m 

X 4 7 * '' X 0 8 » 

X02 * X40 . 

- X 2 0 ( 

-X91 »- X03>-X91 ♦ -X44 t -X2F»-X92 >-X44 . 

- X2F * -X92 f "XOO ? 

"G..@ ...D/.D/.." 


00000020 


.BYTE 

X 4 7 » " X 0 2 » 

- X02 t '' X40 » 

-X20 < 

- X92 »'' XOO 

5 

" G . . @ . . " 


00000028 


.BYTE 

'■ X 4 7 , ' ■ X 0 3 » 

X 0 2 t X 4 0 » 

- X 2 0 ( 

" X93»-XOO 

5 

" G . . i . . " 


00000030 


CD 

m 

"X47 t '' X04 » 

-X02»- X40» 

' X20 < 

-X91 ♦ -X44»-X2C>-X92* -X03 >"X91 »-XOO 

5 

" G . ♦ @ .D »...." 


0 0 0 0 0 0 3 C 


.BYTE 

- xoo, - XOO . 

-xoo»-xoo 



5 



00000040 


.LONG 

- X 0 0 0 0 0 0 0 3 








00000044 

.ADDRESS 

UDAY 

00000048 

.ADDRESS 

UMONTH 

0 0 0 0 0 0 4 C 

.ADDRESS 

UYEAR 

00000050 

.LONG 

XOO000001 

00000054 

.ADDRESS 

SHIPS+88 

00000058 

.LONG 

X00000002 

0000005C 

.LONG 

X00000002 

00000080 

.ADDRESS 

SHIPS 

00000084 

.LONG 

X00000001 

00000088 

.ADDRESS 

SHIPS 
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ooooooec 

00000070 

0000007 a 

00000078 
0000007C 
00000080 
00000084 
00000088 
0000008C 
00000090 
00000094 
00000098 
0000009C 
000000AO 
0 0 0 0 0 0 B 0 
0 0 0 0 0 0 B 8 
0 0 0 0 0 0 C 4 
00000OD4 
0 0 0 0 0 0 E 4 
OOOOOOEC 
0 0 0 0 0 0 F 0 
0 0 0 0 0 0 F 4 
00000OF8 
00000108 

00000000 
00000002 
00000009 
00000010 
00000013 
0000001 A 
00000021 
00000028 


.LONG '>(00000002 
.LONG "X00000001 
.ADDRESS SHIPS 
.LONG "X00000001 
.ADDRESS SUMREP+G8 
.LONG X00000002 
.LONG "X00000002 
.ADDRESS SUMREP 
.LONG -X00000001 
.ADDRESS SUMREP 
.LONG '' X 000 00002 
.LONG "X00000001 
.ADDRESS SUMREP 


BYTE 

"X50 , 

"X52 , ■'X4F 

" X44 , 

"X55 

"X43 , 

* X 5 4 

"X20 

“ X 5 3 , 

-X48 , 

" X 4 9 , 

‘ X50 , 

" X 4 D , 

X 4 5 , 

"X4E , 

'■ X54 

! -PRODUCT SHIPMENT 

BYTE 

'' X 2 0 , 

X 5 2 , " X 4 5 

* X 5 0 , 

X 4 F 

"X52 , 

"X54 










; " REPORT" 

BYTE 

X53 , 

"X48 » "X49 

"X50 , 

" X4D 

X45 , 

" X4E 

" X 5 4 

'X53 








; -SHIPMENTS" 

BYTE 

A X44 , 

" X49 , "X5B 

* X 4 9 , 

"X53 

" X 4 9 , 

"X4F 

"X4E 

"X20 , 

"X20 , 

-X44 , 

'' X 4 5 , 

* X 5 0 , 

' X54 



; "DIOISION DEPT" 

BYTE 

■' X 5 1 , 

"X31 ,"X20 

"X20 , 

'■ X51 

*X32 , 

’■ X 2 0 

" X 2 0 

"X51 , 

"X33 , 

■’ X 2 0 , 

'■ X 2 0 , 

"X51 , 

-X34 , 

"X20 , 

"X20 

; -01 02 03 04 

BYTE 

X 5 4 , 

X 4 F , ■' X 5 4 

" X 4 1 , 

" X4C 












; "TOTAL" 

LONG 

'■ X 0 0 0 00002 















LONG 

"X00000003 















ADDRESS 

SHIPS 















BYTE 

" X 3 C , 

"X3D ,"X3D 

*"X20 , 

'■ X54 . 

* " X G F , 

A X74 , 

"XG1 i 

"XGC , 

o 

CM 

X 

A XGG , 

" X G F , 

’■ X 7 2 




; »< = = Total for" 

BYTE 

" X 3 C , 

"X3D ,"X3D 

> *X20 , 

'■ X 4 7 , 

* '■ X52 , 

-X41 , 

" X 4 E , 

A X44 , 

"■ X 2 0 , 

"X54 , 

" X 4 F » 

"X54 , 

*X41 , 

"X4C 


5 "<== GRAND TOTAL" 


.PSECT $CODE 

.ENTRY SHIPS, 'XOFFC 

MOOAB G"RPG$HANDLER , (FP) 

MOOAB $LOCAL+ '■ X2B , -(SP> 

SUBL2 #"XOC, SP 

MOOAB $ L 0 C A L +"' X 8 0 , Rll 

MOOAB $ P D A T A + ''' X 8 0 , RIO 

MOOAB G''RPG$ IOEXCEPT I ON , R9* 

MOOAB G"RPG$PRINT , R8 


roJram epilogue code 
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00000539 

CALLG 

$PDATA+"X8C(RIO) » 

G"RPG$TERM_PRINT 

00000541 

BLBS 

RO » 72$ 


00000544 

CALLG 

$ P D A T A + " X 9 4 ( R10 ) » 

G"RPG$IOEXCEPTION(R9) 

00000548 

BRB 

73$ 



0000054A 72$: 

0000054A 73$: 

0000054A MOOL #"><01 t RO 

0000054D RET 


SHIPS 



s~ 




28-Jun-1985 

15:58:45 

OAX RPG II 02.0 


Pa 3e 

Cross Reference 

in Alphabetical 

Order (l < 

D 



28-Jun-1985 

15:58:12 

RPG$:CTSAKERES.RPG]SHI PS.RPG \ 1 

. ( 1 ) 


DEPQTY 

19# 

19 

21 

22 








DEPT 

14# 

38 










DIO 

13# 

37 

44 

48 

50 







DIOQTY 

21# 

21 

23 

48 








FINQTY 

23# 

23 

52 









PROD 

15# 

39 










PROOTY 

18# 

19 

41 









QTY 

10# 

IS 

18 

40 








SHIPS 

8# 

12 










SUMREP 

9# 

11 

25 









UDATE 

28 











SHIPS 







28-Jun-1985 

15:58:45 

OAX RPG II 02.0 


Pa Se 

Indicator Cross 

Reference ( 

3 





28-Jun-1985 

15:58:12 

RPG$:CTSAKERES.RPG]SHI PS.RPG5 1 

. ( 1 ) 


01 

12 

18 

19 

38 








LI 

14 

21 

22 

38 

42 







L2 

13 

23 

37 

43 

45 

47 






LR 

51 











IP 

25 

27 

30 

32 









SHIPS 

Compilation Summary 
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PROGRAM SECTIONS 



Name Q. 2 y 

^13^) Bytes 

Attributes 








0 

$CODE 

1358 

PIC 

CON 

REL 

LCL 

SHR 

EXE 

RD 

NOWRT 

Alisn(2) 

1 

$LOCAL 

1280 

PIC 

CON 

REL 

LCL 

NOSHR 

NOEXE 

RD 

WRT 

A1 i S n ( 2 ) 

2 

$PDAT A 

278 

PIC 

CON 

REL 

LCL 

SHR 

NOEXE 

RD 

NOWRT 

A1isn(2) 

3 

RPG$UDATE 

6 

PIC 

OUR 

REL 

GBL 

NOSHR 

NOEXE 

RD 

WRT 

A1 i S n ( 2 ) 

a 

RPG$HALTS 

8 

PIC 

OUR 

REL 

GBL 

NOSHR 

NOEXE 

RD 

WRT 

A1 i S n ( 2 ) 


COMMAND QUALIFIERS (15 


RPG /LIST/MACHINE_CODE/CROSS-REFERENCE/CHECK = ALL/DEBUG/OBJECT/SEQUENCE-CHECK/WARNINGS = ALL SHIPS,RPG 


/CROSS-REFERENCE /MACHINE-CODE /SEQUENCE-CHECK 
/CHECK=(RECURSION .BOUNDS >BLANKS_IN_NUMERICS) 
/DEBUG=(SYMBOLS ♦ TRACEBACK) 

/WARN INGS=(OTHER * INFORMAT I ON) 


STATISTICS 

Time: 

Elapsed Time: 
PaSe Faults: 
amic Memory: 


(0 Run 

© 

© 

© D y n a 


5.26 seconds 
6.58 seconds 
270 

348 eases 





Chapter 12 

Optimizing Your Programs 


The word optimization, as used in this chapter, refers to the process of improving the effi¬ 
ciency of programs. The objective of optimization is to produce programs that achieve the 
greatest amount of processing with the least amount of time, memory and secondary 
storage. 

12.1 Optimizing with Data Structures 

Using data structures to update files can improve the run-time performance of your pro¬ 
grams. This example updates a file with a data structure defined in an Input specification 
and used in an Output specification. 
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0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


F0UT94A UD F 24 

F0UT94B UD F 24 

IGUT94A AA 

I 

I 

I 

I 

I 

I 

I0UT94B AA 
I 

IDS94B DS 

I 

I 

I 

I 

I 

I 


DISK 

DISK 

1 3 PN 

4 10 PNAME 
11 12 UHOUSE 

13 17 COLOR 
18 20 WEIGHT 
22 240QTY 

1 24 DS94B 

1 3 PN2 

4 10 PNAME2 
11 12 UH0US2 

13 17 C0L0R2 
18 20 UEIGH2 
22 240QTY2 


00UT94A E 


0 

PN 

3 

0 

PNAME 

10 

0 

WH0USE 

12 

0 

COLOR 

17 

0 

WEIGHT 

20 

0 

00UT94B E 

QTY 

24 

0 

DS94B 

24 


ZK-4432-85 

Notice in the above program example that the fields to be updated in the Output specifica¬ 
tions for file OUT94B are not listed for a second time, as they would have to be without use 
of a data structure. This results in less written code and a program less prone to error, 
because the layout of the fields is described only once in the data structure. Without a data 
structure, the fields must be described on both the Input and Output specifications. 

12.2 Optimizing With Adjacent Fields in Records 

Note that RPGII extracts adjacent fields from the record buffer with a single VAX MOVE 
instruction and writes them back the same way, which saves time. This optimization is 
performed provided no data conversion is necessary. Therefore, it is a good idea to keep the 
fields contiguous, to avoid requiring multiple MOVE instructions. 
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12.3 Optimizing with Blank Factor 1 

If you use blank Factor 1, you will have less to write and your program will be less prone to 
error because you are not writing the same factor twice. The following example, which is 
part of the above program, demonstrates this technique: 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


I 22 240QTY2 

C# Read records from update files. 

C READ 0UT94A LR 

C NLR READ 0UT94B 

C# Update quantity to reflect the fact that 100 of each part came in. 

C NLR ADD 100 QTY 

C NLR ADD 100 QTY2 

C# Write the updated records. 

C NLR EXCPT 

ZK-4433-85 

12.4 Optimizing File Performance 

You can control file access and improve file performance through optimizing techniques 
discussed in this manual and in the Guide to VAX/VMS File Applications manual. The 
following optimizing techniques are discussed in Part II of this manual: 

• For information on the use of Expansion factors to prevent bucket splitting and to 
improve search efficiency, see Section 2.5.23. 

• For information on file sharing, see Section 2.5.24. 

• For information about multibuffer count, see Section 2.5.21. 

• For information on longer block length for decreasing I/O processing time, see Section 
2.5.9. 

• For information on multiblock count, see Section 2.5.14. 

All of the sections mentioned above point to the Guide to VAX/VMS File Applications man¬ 
ual, which provides pertinent information on tuning sequential, relative, and indexed 
files. That manual also discusses optimizing file performance and processing in a 
VAXcluster, and offers performance recommendations. 
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Chapter 1 

Language Elements 


This chapter describes the following elements of the RPGII language: 

• Character set 

• Datatypes 

• User-defined names 

1.1 RPG II Character Set 

RPG II uses the full ASCII character set. This includes: 

• A through Z, uppercase except for character literals and comment fields 

• The digits 0 through 9 

• Special characters 

Appendix A contains the full ASCII character set and character values. 

1.2 RPG II Data Types 

All data in RPG II input and output operations has a specific data type that determines 
how many bits of storage should be considered as a unit and how the unit is to be inter¬ 
preted and manipulated. 

RPG II supports five different data types for data in input and output operations. Follow¬ 
ing sections describe each data type. 

• Character 

• Word binary numeric 

• Longword binary numeric 
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• Packed decimal 

• Overpunched decimal 

1.2.1 Character 

Character data is a string of bytes containing ASCII codes as binary data. The length can 
be from 1 to 9999 bytes. The format of a character string is illustrated in Figure 1-1. 

NOTE 

In all subsequent diagrams, A represents the address of the first byte of the 
string and L represents the length of the string in bytes. 

7 0 




A + L - 1 


ZK-1452-83 


Figure 1-1: Character String 

The address of a string specifies the first character of a string. XYZ is represented in Fig¬ 
ure 1-2. 

—*- A + 1 

^ - A + 2 

83 

Figure 1-2: Address of a String 
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1.2.2 Binary 

Binary data is stored as binary values in a word or a longword. A word is two contiguous 
bytes, starting on an arbitrary byte boundary. The bits are numbered from the right (0 
through 15). When interpreted as a signed quantity, a word is a two’s complement number 
with bits increasing in significance from bit 0 through bit 14, and with bit 15 designating 
the sign. A two byte word supports up to four decimal digits. The largest number that can 
be represented by a word in RPGII is 9,999. A word is represented in Figure 1-3. 

15 0 


A 
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Figure 1-3: Word Data Type 

A longword is four bytes, starting on an arbitrary byte boundary. The bits are numbered 
from the right 0 through 31. When interpreted as a signed quantity, a word is a two’s com¬ 
plement number with bits increasing in significance from bit 0 through bit 30, and with bit 
31 designating the sign. A four byte longword supports up to 11 decimal digits. The largest 
number that can be represented by a longword in RPG II is 99,999,999,999. A longword is 
represented in Figure 1-4. 
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Figure 1-4: Longword Data Type 


1.2.3 Packed Decimal 

Packed decimal data is stored as a string of bytes. Each byte is divided into two 4-bit half 
bytes (nibbles), with one decimal digit stored in each half byte. The first, or most signifi¬ 
cant, digit is stored in the high-order half byte of the first byte, the second is stored in the 
low-order half byte of the first byte, the third digit is stored in the high-order half byte of 
the second byte, and so on. The sign of the number is stored in the low-order half byte of the 
last byte of the string. The number +123, in packed decimal format, is represented in 
Figure 1-5. 
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7 


4 3 


0 


1 

2 

3 

12 


A 


A + 1 


ZK-1455-83 


Figure 1-5: Packed Decimal Data Type 

A decimal 10,12,14, or 15 represents a plus sign, with 12 used when the number is created 
as a result of a VAX arithmetic instruction. A decimal 11 or 13 represents a minus sign, 
with 13 used when the number is created as a result of a VAX arithmetic instruction. 

The following formula can be used to determine the length in digits of a packed decimal 
field: 

number of digits = 2n -1 
where n = number of bytes used 

See Part II, Section 2.8.15 for examples of selecting numeric data types in an RPG II 
program. 

1.2.4 Overpunched Decimal 

Overpunched decimal data is a contiguous sequence of bytes in memory, with one decimal 
digit in a byte. Digits of decreasing significance are assigned to increasing addresses. The 
sign is superimposed on the last digit (trailing numeric string). 

All bytes of overpunched decimal data, except the least significant digit, must contain 
ASCII decimal digit characters (0 through 9). Table 1-1 lists the representation for these 
nonleast significant digits. 
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Table 1—1: Overpunched Decimal Representation of Nonleast Significant Digits 


Sign 

Decimal 

Hexadecimal 

ASCII Character 

0 

48 

30 

0 

1 

49 

31 

1 

2 

50 

32 

2 

3 

51 

33 

3 

4 

52 

34 

4 

5 

53 

35 

5 

6 

54 

36 

6 

7 

55 

37 

7 

8 

56 

38 

8 

9 

57 

39 

9 


There are several variations of overpunched decimal format. Alternate forms of 
overpunched decimal format are accepted on input. The normal form of overpunched deci¬ 
mal format is generated on output. Valid representations of the digit and sign in each of 
the latter two formats (input and output) are shown in Table 1-2. 

Table 1-2: Overpunched Decimal Representations of Least Significant 
Digit and Sign 


Overpunched Decimal Format ASCII Characters 


Digit 

Decimal 

Hexadecimal 

Normal 

Alternate 

0 

48 

30 

0 

{[? 

1 

49 

31 

1 

A 

2 

50 

32 

2 

B 

3 

51 

33 

3 

C 

4 

52 

34 

4 

D 

5 

53 

35 

5 

E 

6 

54 

36 

6 

F 

7 

55 

37 

7 

G 

8 

56 

38 

8 

H 

9 

57 

39 

9 

i 

-0 

125 

7D 

} 

]:! 

-1 

74 

4A 

J 


-2 

75 

4B 

K 


-3 

76 

4C 

L 


-4 

77 

4D 

M 


-5 

78 

4E 

N 


-6 

79 

4F 

O 


-7 

80 

50 

P 


-8 

81 

51 

Q 


-9 

82 

52 

R 
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The following diagrams illustrate the representation of 123 and -123 in trailing numeric 
string format. Figure 1-6 represents 123 and Figure 1-7 represents -123. 


7 4 3 0 


3 

1 

3 

2 

3 

3 


A 


A + 1 


A + 2 


Figure 1-6: Overpunched Decimal Data Type 

7 4 3 0 


3 

1 

3 

2 

4 

C 


Figure 1-7: Overpunched Decimal Data Type 


ZK-1456-83 


A + 1 


A + 2 


ZK-1457-83 


1.3 USER-DEFINED NAMES 

A user-defined name is a named quantity that identifies an entity in an RPGII program. 
The name you define specifies the following entities: 

• Files 

A file name is assigned to a file. 

• Fields 

A field name is assigned to a field in a program. You can use a field name in more than 
one field definition if each definition using that name has the same data type, the 
same length, and the same number of decimal positions. 
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• Arrays 

An array name is assigned to an array. The first three characters cannot be TAB. 

• Tables 

A table name is assigned to a table. The first three characters must be TAB. 

• Labels 

A label identifies the destination point for a GOTO operation code. 

• Subroutines 

A subroutine name is assigned to a subroutine. 

• PLIST 

A PLIST name is assigned to a list of parameters to be passed to a subprogram. 

• EXCPT 

An EXCPT name can be used in Factor 2 of the EXCPT operation code and in the 
Field name field of exception record 0 specifications. 

When defining a name, observe the following rules: 

• The first character of a name must be one of the following: 

- A letter A through Z 

- An underscore (_) 

- A pound sign (#) 

• The remaining characters of a name can be the letters A through Z, the numbers 0 
through 9, an underscore (_), or a pound sign (#). 

• You must left-justify names. 

• You cannot embed blanks in a name. 

• You cannot use an RPGII special word as a name. See Part I, Chapter 6 for informa¬ 
tion on special words. 

• The maximum length of a name is six characters, except for a file name, which can be 
up to eight characters. 

• Every user-defined name must be unique. For example, a name assigned to a file can¬ 
not be used as a field name. 
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Chapter 2 

Specifications 


This chapter describes the following RPGII specifications: 

• Control 

• File Description 

• Extension 

• Line Counter 

• Input 

• Calculation 

• Output 

Each specification description includes the following information: 

• A brief explanation of the purpose of the specification 

• The specification’s format 

• A detailed explanation of each column: 

- A brief explanation of the column’s purpose 

- A table listing valid entries for the column 

- An example of a typical use 

Use the information in this chapter for quick reference. Consult the Table of Contents or 
Index for information on topics requiring a more detailed explanation. 
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2.1 Notation Conventions 


This section describes the notational conventions of the specifications described in this 
chapter. 

Two rows of digits identify column numbers, as shown in the following example: 


0 I 1 I 2 I 3 14 I 5 I 6 I 71 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


ZK-4454-85 


The arrow in the following example points to column 43. 



In the previous example, the vertical line above the first zero separates columns 30 
through 39 from columns 40 through 49; the vertical line above the second zero separates 
columns 40 through 49 from columns 50 through 59. 


0111213141516171 
■12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# ....... 

ZK-4455-85 
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Asterisks (*) in the dotted line below the two rows of column numbers indicate the begin¬ 
nings of fields that can have values for the specification being described. Each field is ter¬ 
minated by another asterisk, by a dot, or by column 75. 

The positions of the asterisks are different for each specification. 

The asterisk in the example above indicates that you can enter a value in column 6. 

The dots in the line below the two rows of column numbers identify fields that must be 
blank. 


0 I 1 I 2 I 3 t 41 51 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** ******-*-**“*** *-** * * . *-**,.** . . 

ZK-4456-85 

Dashes after an asterisk indicate a field that must contain numeric data. Numeric data, if 
entered, must be right-justified in the field. Blanks after an asterisk indicate a field that 
must contain alphanumeric data. Alphanumeric data, if entered, must be left-justified in 
the field. 
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In the following example, the value 32 has been entered in columns 20 through 23; the 
value 41 has been entered in columns 24 through 27; no value has been entered in column 
28; the value 9 has been entered in columns 29 and 30; and no value has been entered in 
column 31. 



32 4i 9 


ZK-4457-85 


2.2 Common Fields 

This section describes fields that are common to all specifications. 

2.2.1 Line Number 

You can associate a line number with each line in your program. Line numbers are 
optional, but can be used to check the sequence of lines. To check line numbers, you must 
specify the SEQUENCE_CHECK qualifier to the RPG command. If you do not, RPGII will 
ignore all line numbers. The absence of line numbers does not affect your program. 

Column Allowable Explanation 

Number Values 

1-5 Any number Associates a line number with the program line 

Additional Information 

If you specify the SEQUENCE_CHECK qualifier to the RPG command and the line num¬ 
bers are out of sequence, RPG II will issue a warning compile-time error. 
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2.2.2 Specification Type 

You must identify the type of specification on every program line. Use column 6 to specify 
the type of specification. 


Column Allowable Explanation 

Number Values 


6 H 

F 

E 

L 

I 

C 

O 


Specifies that the program line is a Control specification 

Specifies that the program line is a File Description 
specification 

Specifies that the program line is an Extension 
specification 

Specifies that the program line is a Line Counter 
specification 

Specifies that the program line is an Input specification 

Specifies that the program line is a Calculation 
specification 

Specifies that the program line is an Output specification 


2.2.3 Comments 

Use columns 75 through 80 to write comments about the program line. RPG II ignores 
entries in columns 75 through 80. In other implementations of RPG II, these columns are 
used for a program name. RPG II uses the source file name as the name of the program. 

Column Allowable Explanation 

Number Values 

75—80 Any character Documents the program line 

Rules 

• Blank lines can appear between any two specifications. RPG II ignores blank lines. 

• A specification containing only a form feed can appear between any two specifica¬ 
tions. Specifications containing only a form feed are treated like blank lines except in 
the listing file, where they cause the listing to skip to the top of the next page. 

Additional Information 

You can also use an entire specification to write a comment when you precede the comment 
with an asterisk in column 7. You can do this with any type of specification. However, col¬ 
umn 6 must contain an entry for a specification type. 
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2.3 Compiler Directing Statements 

A copy directive allows you to copy one or more source files into the main source file during 
compilation. This feature can be used for copying in common subroutines, record defini¬ 
tions, or other useful information. 

Rules 

• A copy directive may appear anywhere within the source file before the first double 
slash (//) or double asterisk (**) line. It cannot appear after that, because the remain¬ 
ing lines do not contain a specification type. 

• A copy directive cannot appear within a long character literal. 

• There is no limit on the number of copy directives in a program. 

• Copy directives cannot be nested. A file copied in cannot contain a copy directive or a 
COPY_CDD. 

Copy directives can be followed by modifier statements, which supply additional informa¬ 
tion on preceding Input specification fields. See Section 2.3.3 for the syntax and rules of 
modifier statements. 

If you specify the SEQUENCE qualifier, then the copied lines are sequence checked sepa¬ 
rately from the main source file. 

Copy and copy from CDD lines are always listed in the listing file. The copied lines imme¬ 
diately follow the copy directive line in the listing. Each line is given a unique listing line 
number. A “C” is placed after the line number in the listing record to indicate that the line 
was generated by a copy directive. There is still a single set of line numbers to mark the 
entire source file, after allowing for text that has been copied into the main source file. 

If a COMPILE command is issued from the editor and an error is flagged within the compi¬ 
lation of a COPY or COPY_CDD directive, the cursor is placed at the copy directive, and 
the message is displayed on the message line. You must leave the editor if you want to see 
the compiler source listing. 
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2.3.1 Copy 

Copy directives adhere to the following rules: 

• A copy directive must appear on a line of its own, and have the following syntax: 

- Column 6 - Any valid specification type (not checked for sequence) 

- Columns 7 through 12 - Must contain “/COPY ” (note the blank space in 
column 12) 

- Columns 13 through 74 - Contain the file specification enclosed in single quotes; 
the file specification does not have to start in column 13 

• A default file type of RPG is used 

Following is an example that copies in the file, 
SO_MUCH_TIME__AND_SO_LITTLE_TO_DO.RPG 


0 I 1 I 2 I 3 I 4 I 5 I 6 I 71 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


##> # # # # # #—### # # # 

C/C0PY 'S0-MUCH JTIME JWD-SQ J_ITTLE_T0_DQ' 

ZK-4458-85 


2.3.2 Copy from CDD 

Record definitions can be stored in the Common Data Dictionary (CDD) and shared among 
RPG programs. You can extract these data definitions from the CDD and use them as field 
definitions on Input or Output specifications. If you change a definition in the CDD, you do 
not have to rewrite the program using it; however, you must recompile the program to 
obtain the latest definition in the CDD. 

The following example shows how to copy field information from the CDD, on an Input 
specification. 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### #— *— *— .##—*—** ***#**,.. . 

I/C0PY-CDD 'RECORD.IN' 

ZK-4459-85 

RECORD.IN is the CDD path name for a record description stored in the CDD. A path 
name must be enclosed in single quotation marks; note that the pathname does not have to 
start in column 17. 

For information on CDD pathnames, see the VAX Common Data Dictionary Users Guide. 
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The CDD provides RPG-specific features. These are: NAME FOR RPG, EDIT_WORD 
FOR RPG, and EDIT_CODE FOR RPG. These attributes are discussed in the VAX Com¬ 
mon Data Dictionary Reference Manual. 

The two examples below show field definitions entered in the CDD, and the Input specifica¬ 
tions that must be entered to extract the information. 

Using the CDDL utility, these field definitions are entered: 

DEFINE RECORD CDD$TOP♦EXAMPLE♦ADDRESS-RECORD 
ADDR STRUCTURE♦ 

STREET DATATYPE IS TEXT 

SIZE IS 30 CHARACTERS 
CITY DATATYPE IS TEXT 

SIZE IS 30 CHARACTERS 
STATE DATATYPE IS TEXT 

SIZE IS 2 CHARACTERS 

PHONE STRUCTURE♦ 

AREA DATATYPE IS NUMERIC RIGHT OVERPUNCHED 

SIZE IS 3 DIGITS 

NUMBER DATATYPE IS NUMERIC RIGHT OVERPUNCHED 

SIZE IS 7 DIGITS 

NA ME FOR RPG IS P# 

END PHONE STRUCTURE♦ 

END ADDR STRUCTURE♦ 

END ADDRESS.RECORD* 

In the RPG II program, these Input specifications are entered: 


0I1I2I3I4I5I6I7I 
HBBSlBl 2345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### # - # - *- .*#-*-** ###### .... 

IINFO AA 

I/COPY-CDD 'EXAMPLE.ADDRESS-RECORD' 

ZK-4460-85 
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The information is extracted from the CDD and parsed as though the user had entered the 
following: 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** 

* *«« *— 

# - # - 

. ##-#• 

—## 

I INFO 

AA 




I 



i 

30 STREET 

I 



31 

60 CITY 

I 



61 

62 STATE 

I 



63 

72 PHONE 

I 



63 

650AREA 

I 



66 

720P# 


ZK-4461 -85 

2.3.3 Copy Modifiers 

To include indicators on Input fields copied from the CDD you must enter a modifier state¬ 
ment after the COPY_CDD statement. You can modify any field in the current record 
including those copied from the CDD. The following fields can be modified: 

• Control-level indicator 

• Matching fields 

• Field-record-relation 

• Field indicators 

Rules 

• A modifying statement is distinguished from other specifications by an ampersand 
(&) in column 7. 

• Only specifications that define fields can be modified. 

• As many modifiers as desired can be specified on one modifier specification. 

• The same field can be modified by multiple modifiers. 

• A field specification must be syntactically valid before and after a modifier is applied. 
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A modifier can be used to add an indicator where there was none in the original specifica¬ 
tion. The following example shows a level indicator set on the AREA field in the above 
program. 


I 0 I 1I 2 I 3 \ 4 I 5 I 6 T 7 n 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## * ### * - # - # - .##-*-## ##*### .... 

IINF0 AA 

I/C0PY-CDD 'EXAMPLE.ADDRESS-RECORD' 

I& AREA Li 

ZK-4462-85 


The field AREA is treated as if it had been specified with LI in the control level indicator 
field, that is, as if the specification had been as follows: 


0 I 1 I 2 13 I 4151 6 I 71 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


I 63 650AREA Li 

ZK-4463-85 


A modifier can be used to supersede a previously specified value. You can also blank a field 
by entering the an ampersand (&) as the first character of the desired field, and leaving the 
rest of the field blank, as in the following example. 

This example assumes that the file to be copied (MSL27A.RPG) contains the following 
specification: 


0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # *## # - * - #- .## -#-## #####*,.. . 

I 6 6 FLDA 01 

ZK-4464-85 


** 


* ### #- *- #- 


, ##-#-*# 


# # # * * # . . . . 


IMSLI27 01 1 CA 

I/COPY 'MSL27A' 

I& FLDA & 


ZK-4465-85 
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In the above example, FLDA is treated as if no field-record-relation indicator is given, for 
example, as if the Input specification is: 


011 1213)41516171 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### * # - * . ## # ## ###### . . . . 

I 6 6 FLDA 

ZK-4466-85 

Modifiers can apply to all field definitions that follow the record containing the last COPY 
or COPY_CDD directive. In the above example, if FLDA occurred several times in the 
copied file, each occurrence would be modified. 

If the source program looked like the example below, then only the occurrences of the 
FLDA field associated with the second copy directive would be modified. 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### # — #— #— ,##—#—## ##*### .... 

IMSLI27 AA 01 
I/COPY 'MSL27A' 

I BB 02 

I/COPY 'MSL27A' 

Ift FLDA & 

ZK-4467-85 

When a modifier specification is not preceded by a copy directive, all previous input fields 
can be modified. 


2.4 Control Specification 

The Control specification allows you to do the following: 

• Assign a character other than the default (a dollar sign ($)) as the currency symbol 

• Specify the notation for numeric fields, Edit codes, and UDATE 

• Define an alternate collating sequence 

• Check the alignment of printed forms 

A Control specification is not required. Complete the specification only when you need to 
define the use of one or more items described in the list above. Use only one Control specifi¬ 
cation in a program. 
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2.4.1 Control Specification Format 

The format of the Control specification is: 


Currency symbol 
I Inverted print (DIJ) 

I I Alternate collating sequence (SE) 
III IP forms position (i) 

III I 

H III I 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#... .#.. 

ZK-4468-85 


2.4.2 Specification Type 

Use column 6 to identify the type of specification for every program line. 

Column Allowable Explanation 

Number Values 

6 H Indicates that this program line is a Control specification 

2.4.3 Currency Symbol 

Use column 18 to specify a character other than the dollar sign ($) to represent the cur¬ 
rency symbol. 

Column Allowable Explanation 

Number Values 

18 Blank Uses the dollar sign ($) as the currency symbol. The dollar 

sign is the default. 

Character Uses the character you specify instead of the dollar sign ($) 

for the currency symbol. 

You can use any character for the currency symbol except zero (0), asterisk (*), comma (,), 
ampersand (&), decimal point (.), minus sign (-), C (C), and R (R). 

2.4.4 Inverted Print 

Use column 21 to specify the notation the printer uses for numeric fields, Edit codes, and 
UDATE. 
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Column Allowable Explanation 

Number Values 

21 Blank Uses a period as the decimal notation and a comma as the 

thousands separator in numeric literals and Edit codes 
(for example, 1,234.56 and .56). Uses a slash (/) as the 
separator for the Y Edit code; uses the month/day/year for¬ 
mat for UDATE (for example, 03/24/85). See Section 
2.10.14 for information on Edit codes. See Part I, Chapter 6 
for information on UDATE. 

D Uses the same format as the Blank option for numeric 

literals and Edit codes. Uses a slash (/) as the separator for 
the Y Edit code; uses the day, month, and year (ddmmyy) 
format for UDATE. 

I Uses a comma as the decimal notation and a period as the 

thousands separator in numeric literals (for example, 
1.234,56) and Edit codes. Uses the day, month, and year 
(ddmmyy) format for UDATE; decimal points separate the 
day, month, and year elements (for example, 24.03.85). 

J Uses the same format as the I option for UDATE, numeric 

literals, and Edit codes with the following exception: 
writes a zero to the left of the comma when the field con¬ 
tains only a fraction (for example, 0,56). 

2.4.5 Alternate Collating Sequence 

Use column 26 to specify the collating sequence you want RPG II to use when comparing 
character fields using the COMP operation code and when checking the sequence of match¬ 
ing fields. 

Column Allowable Explanation 

Number Values 

26 Blank Uses the ASCII collating sequence. See Appendix A for the 

ASCII character set. 

E Uses the EBCDIC collating sequence. See Appendix A for 

the EBCDIC character set. 

S Uses a user-defined collating sequence. See Appendix A 

for the ASCII characters and their hexadecimal values. 
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To define a collating sequence that is different from the standard ASCII or EBCDIC 
sequences, you must specify the hexadecimal value of each character whose position in the 
sequence you want to change. To do this you must 

• Specify S in column 26 of the Control specification. 

• Include the specification for ALTSEQ records after the Output specification, but 
before any compile-time table and arrays, if used. 

• Precede the ALTSEQ records with double slashes (//) and a blank or double asterisks 
(**) and a blank in columns 1 through 3. 

• Specify the following entries: 


Column 

Number 

Allowable 

Values 

Explanation 

1-8 

ALTSEQbb 

Indicates that you are specifying an alternate collating 
sequence. Note that bb represents two blanks. 

9,10 

Hexadecimal 

value 

Specifies the hexadecimal value of the character you want 
to change. 

11,12 

Hexadecimal 

value 

Specifies the new hexadecimal value of the character 
whose position in the collating sequence you want to 
change. 


Repeat this sequence of hexadecimal numbers up to column 80 for additional changes. The 
first blank space in an ALTSEQ record terminates the ALTSEQ entries for that record. 
The rest of the line can be used for comments. 


In the following example, columns 9 and 10 and 13 and 14 contain the hexadecimal value 
of the character to be changed, and columns 11 and 12 and 15 and 16 contain the new hex¬ 
adecimal value of the character. In the following collating sequence, RPG II changes the 
uppercase Z (5A) to an uppercase A (41) and the lowercase w (77) to an uppercase J (4A). 


0 I 1 I 2 I 3 I 41 5 I 6 I 7 ! 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** 

// 

ALTSEQ 5A41774A 

ZK-4469-85 
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2.4.6 Forms Position 

Use column 41 to check the alignment of printed output on a nonstandard form. 

Column Allowable Explanation 

Number Values 

41 Blank Specifies no forms-positioning check 

1 Checks the forms positioning by printing the first output 

line 

This entry is optional and valid only for a nonspooled device. 

Additional Information 

When you specify Forms positioning, the printer outputs the first line. Then, RPGII asks 
the following question for each printer output file in the order that the first lines are 
output: 

Is forms position ins correct? 

Yes > type Continue » No > type Retry; 

If you type Continue, the program will print the second output line, and so on, until all 
lines are output. If the forms are not correctly positioned, realign the form, and then type 
Retry. RPG II will print the first line again so that you can determine whether the form is 
positioned correctly. 

2.4.7 Example 

In the following example, the following control characteristics are defined: 

• Program line is a Control specification. 

• Currency symbol is a pound sign (#). 

• RPG II uses: 

- A comma (,) as the decimal notation for numeric literals and Edit codes 

- A period (.) as the thousands separator for numeric literals and Edit codes 

- The ddmmyy format for UDATE with a period (.) separating the day, month, and 
year elements 

• Collating sequence is EBCDIC. 

• Forms-positioning check is not required. 
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Currency symbol 
I Inverted print (DIJ) 

I i Alternate collating sequence (SE) 
III IP forms position (i) 

III I 

H III I 


0 I 1I 2I 3I 4 I 5 I 6 I 7 N 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


# .. # 

H HIE 


ZK-4470-85 


2.5 File Description Specification 

The File Description specification describes the attributes of each file you use in your 
program. 

2.5.1 File Description Specification Format 

The format of the File Description specification is: 


Mode (LR) 

I Key length 



Type (I0UD) II 

Record address type (API) 


Addtn(AU) 


IDes (PSRCTD)11 

1 Organization <IT,i-9) 


1 Expand 


IIEOF (E) II 

MOverflow indicator 


11 Share 


IllSeq (AD) II 

III Key location 


111 Rewnd 

File 

llllFmt (FV) II 

III 1 Extension (EL) 


III 1 

name 

IIIIIBlk Rec II 

III 1 1 Device Symb Tape 

Core 

III IFile 

1 

llllllen len II 

III 1 Icode dev label 

index 

III Icond 

FI 

llllll 1 II 

III 1 II II 

1 

III II 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## ######—#—a#-####—## # -###,## .. 


ZK-4471-85 


2.5.2 Specification Type 

Use column 6 to identify the type of specification for every program line. 

Column Allowable Explanation 

Number Values 

6 F Indicates that this program line is a File Description 

specification 
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2.5.3 File Name 


Use columns 7 through 14 to identify the files you use in an RPGII program. 

Column Allowable Explanation 

Number Values 

7-14 File name Identifies the file 

Rules 

• The number of files you can open depends on the Open File Quota set by your system 
manager. To determine the number of files you can open in an RPG II program, type 
the SHOW PROCESS/QUOTA command and look for the number to the right of Open 
File Quota:. 

• The specification options explained in Sections 2.5.4 through 2.5.26 all apply to the 
file you identify in columns 7 through 14. 

• VAX RMS uses the file name as the default file specification string. See Part I, Chap¬ 
ter 5 for information about how RPG II uses the File name field and the Symbolic 
device field to generate the VAX/VMS file specification. 

2.5.4 File Type 

Use column 15 to specify the File type that defines how RPG II processes the records in the 
file. 

Column Allowable Explanation 

Number Values 

Designates an input file. RPG II reads the records from an 
input file and uses these records as data. These records 
must be defined in Input specifications unless column 16 
contains R or T. Input files can reside on disk or tape, or 
can be read from a terminal or from cards. 

Designates an output file. The program writes or prints 
the records of an output file. These records must be defined 
in Output specifications unless this is a table output file. 
Output files can be written to a printer, disk, tape, or ter¬ 
minal. 

Designates an update file. Update files must reside on 
disk. RPG II can read, change, and write records in an 
update file. The records in these files must be defined in 
the Input and Output specifications. 


15 I 


O 


U 
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Column Allowable Explanation 
Number Values 

D Designates a display input or output file. Use display files 

to accept input from a terminal or to display output on a 
terminal. You must complete a Calculation specification to 
define the fields you want to display using the DSPLY 
operation code. See Part II, Chapter 3 for information on 
the DSPLY operation code. 


2.5.5 File Designation 

Use column 16 to specify File designation that defines the order of processing files. See 
Part I, Chapter 5 for information on processing files. 


Column Allowable Explanation 
Number Values 


16 Blank 

P 


S 

R 


Specifies a nonchained output file or a display file. 

Specifies a primary file. You can use only one file as the pri¬ 
mary file. It can be an input or an update file. In multifile 
processing, the primary file determines the order of record 
selection; in single file processing, the primary file pro¬ 
vides all input records. If a primary file is not specified and 
one or more secondary files are specified, the first secon¬ 
dary file is assigned as the primary file. If no primary or 
secondary files are specified, you must provide an exit for 
your program by setting on the LR indicator. 

Specifies a secondary file. A secondary file can be an input 
or an update file. See Part I, Chapter 5 for information on 
processing secondary files. 

Specifies a record-address file. A record-address file indi¬ 
cates which records to process and the order in which they 
are to be processed. This file must be associated with a file 
defined in an Extension specification. See Part I, Chapter 5 
for information on record-address files. 
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Column Allowable Explanation 

Number Values 

C Specifies a chained file. A chained file resides on disk and 

can be used as an input, output, or update file. You use the 
CHAIN operation code in the Calculation specification to 
randomly read records from a chained file. You use an out¬ 
put chained file to add records to a direct file. The CHAIN 
operation positions the file before RPG II writes each 
record. See Part II, Chapter 3 for more information on 
chained files. 

T Specifies a pre-execution-time table or array. You must 

enter, in columns 11 through 18 of the Extension specifica¬ 
tion, the name of the file that contains the data from which 
you want to load the table or array. See Part I, Chapter 7 
for information on tables. See Part I, Chapter 8 for infor¬ 
mation on arrays. 

D Specifies a demand input or update file. You can use the 

READ operation code in the Calculation specification to 
sequentially access the records in a demand file. See Part 
II, Chapter 3 for more information on using the READ 
operation code to access records from demand files. 

F Specifies a full-procedural input or update file. You can use 

the READ and/or CHAIN operation code in the Calcula¬ 
tion specification to sequentially and/or randomly access 
the records. 

2.5.6 End-of-File 

Use column 17 to specify end-of-file that indicates whether or not the program can end 
before RPG II processes all the records in the file. 

Column Allowable Explanation 

Number Values 

17 Blank Causes the program to finish reading all the records from 

every primary and secondary file before ending, if column 
17 is blank for all primary and secondary files. If column 
17 is not blank for all primary and secondary files, RPG II 
may or may not process all the records in this file (the file 
described in this specification). If column 17 is blank for all 
primary and secondary files, RPG II processes all the 
records in this file (the file described in this specification). 
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Column Allowable Explanation 

Number Values 

E Causes the program to finish reading the records in the file 

before ending the program, regardless of the presence of 
other files. You can use this option for input or update files 
as primary, secondary, or record-address files. You cannot 
use this option on a file being processed by a record- 
address file. 

When you specify E in column 17 for the primary file, and 
there are matching records in the primary and secondary 
files, RPGII reads and processes any records in the secon¬ 
dary file that match the last record of the primary file 
before ending the program. 

2.5.7 Sequence 

Use column 18 to specify the sequence to check matching fields, either ascending or 

descending. See Part I, Chapter 5 for information on matching fields. 

Column Allowable Explanation 

Number Values 

18 Blank Indicates that the program contains no matching fields or, 

if it does, assumes the same value as specified for a previ¬ 
ous primary or secondary file. If the program contains 
matching fields and you do not specify a sequence for any 
file containing matching fields, RPG II assumes an ascend¬ 
ing order. 

A Checks matching records for ascending order. 

D Checks matching records for descending order. 

Rules 

• This entry applies only to primary or secondary files with matching fields. See Part I, 
Chapter 5 for more information. 

• This entry must be the same for each file you process with matching fields. 
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2.5.8 File Format 


Use column 19 to specify File format. File format specifies whether the records in the file 
are all the same length, or whether they can be of different lengths. You can save process¬ 
ing time if all the records are the same length and each record is completely filled with 
data. If the records are not completely filled with data, you waste space. Variable-length 
records use space more efficiently, but take longer to process. 

Column Allowable Explanation 

Number Values 

19 F 

V 

Rules 

• If you specify variable-length records, RPG II uses the highest value in columns 40 
through 43 in the Output specification as the length for that record. 

• You must specify fixed-length records for sequential files being processed as update 
files. 

Additional Information 

When a variable-length record is read, RPG II fills the unused portion of the input buffer 
with spaces. Character fields with characters beyond the end of the record will be filled 
with spaces. Numeric fields with digits beyond the record will be filled with spaces. This 
condition will cause a run-time error, unless you use the 
CHECK:BLANKS_IN_NUMERICS qualifier with the RPG command. A numeric field in 
packed decimal or binary format cannot extend beyond the end of the input record. If it 
does not, unpredictable results will occur. 

2.5.9 Block Length 

Use columns 20 through 23 to specify the length of a block. Data is stored in physical 
records called blocks. A block is the smallest number of bytes RPG II transfers in a physi¬ 
cal read or write operation. 

In general, by specifying a longer block length, you decrease I/O processing time because 
more records will be available at any given time. For example, a program that loads a 
single key indexed file with approximately 1700 80-byte records could see a decrease in 
direct I/Os of about 60% and a decrease in elapsed time of 40-50%. This would occur when 
the block length is increased from 512 (RMS bucket size of 1) to 4096 (RMS bucket size of 
8). However, do not specify a block length that exceeds the Working Set Quota. To display 
the Working Set Quota, type the following: 

$ SHOW WORK ING_SET 

For more information on quotas see the VAX/VMS Guide to File Applications. 


Indicates that all records are the same (fixed) length 
Indicates that records can be of different (variable) lengths 
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Column Allowable Explanation 

Number Values 

20-23 Blank Uses the same entry for Block length as the Record length 

(columns 24 through 27) 

1-9999 Specifies the bucket size (in bytes) for those direct and 

indexed files being created on disk, or specifies the Block 
length (in bytes) for files on tape 

Rules 

• For disk files, the block length you specify sets the VAX RMS bucket size parameter. 
RPG II divides the block length you specify by 512 and rounds the result to the next 
highest integer, if necessary For example, if you specify a block length of 2048 bytes, 
the VAX RMS bucket size is 4. 

• For disk files, the minimum block length is 512 bytes. 

• For tape files, the block length you specify sets the VAX RMS block size parameter. 
The block length must be either (1) equal to the entry in columns 24 through 27 
(Record length) of the File Description specification, or (2) an integer multiple of the 
record length. In either case, the block length cannot be greater than the maximum 
record length for the device. See your system manager for the maximum record 
length. 

To make your tape compatible with non-DIGITAL systems, use the ANSI standard 
block length: less than or equal to 2048 bytes. 

• Right-justify this entry. 

• Leading zeros can be omitted. 

2.5.10 Record Length 

Record length specifies the length of each fixed-length record in a file, or the maximum 
length for variable-length records. 


Column 

Number 

Allowable 

Values 

Explanation 

24-27 

1-9999 

Specifies the number of characters in each record 

Rules 




• The record length for fixed-length records in an update file must be the same value 
you used to write the records. 

• Right-justify this entry. 

• Leading zeros can be omitted. 
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2.5.11 Mode of Processing 

Use column 28 to specify the method RPGII uses to access records in a file. Your choice of 
processing method depends on the entries for File designation and File organization. Your 
choice of processing method for input and update files depends on the entries for the File 
type, the Mode of processing, the Record address type, and File organization. Refer to 
Tables 2-1 through 2-3 to select the correct value. 


Column Allowable Explanation 
Number Values 


28 Blank 

L 

R 


Additional Information 


Accesses records sequentially, or accesses records sequen¬ 
tially by key 

Accesses records sequentially within limits 

Accesses records randomly, using a relative record num¬ 
ber or an index key, or using an ADDROUT file, or tells the 
program to load a direct file 


• Sequential processing reads the records in the order in which they were written. 

• Sequential by key processing reads records from indexed files that are used as pri¬ 
mary, secondary, or demand files. The key refers to the index, which is read in ascend¬ 
ing order. 

• Sequential-within-limits processing reads records in one of two ways: 

- Specifying a range of records to be read. 

- Using the SETLL operation code in the Calculation specification to set the lowest 
key for the records in a demand file. The program reads records with keys equal to 
or higher than the key you specify. 

• Random processing reads records from chained files in one of the following two ways: 

- For sequential or direct files, records are accessed by their relative record number. 
A relative record number identifies the position of a record relative to the begin¬ 
ning of the file. 

- For indexed files, records are accessed by their index key values. 

• ADDROUT file processing uses the ADDROUT file generated by the VAX/VMS 
SORT/MERGE utility. The ADDROUT file contains binary record numbers that cor¬ 
respond to the addresses of records, therefore, the records to be read are located by 
their addresses. 

• Files on devices other than disk can be accessed only sequentially. 
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Legend for Tables 2-1 through 2S 


Symbol 

Meaning 

P 

Primary file 

S 

Secondary file 

I 

Indexed file 

c 

Chained file 

T 

Table 

F 

Full-Procedural file 

b 

Blank 

R 

Random 

L 

Sequential within limits 

A/P 

Alphabetic or Packed keys 

(1-9) 

Additional areas 


For input or update primary, secondary, or demand files that reside on disk, you can use the 
entries listed in the following table: 

Table 2-1: Modes of Processing for Primary, Secondary and Demand Files 


File 

Organization 

Allowable 
Acccess Modes 

Allowable 

Entries 






Column: 






16 

28 

31 

32 


Sequential 

Sequential 

P 

b 

b 

b 

(b or 1-9) 



s 

b 

b 

b 

(b or 1-9) 



D 

b 

b 

b 

(b or 1-9) 



F 

b 

b 

b 

(b or 1-9) 

or 


— 





Direct 

ByADDROUT 

P 

R 

I 

b 

(b or 1-9) 


file 

S 

R 

I 

b 

(b or 1-9) 


(continued on next page) 
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Table 2-1: Modes of Processing for Primary, Secondary and Demand Files 

(Cont.) 


File 

Organization 

Allowable 
Acccess Modes 

Allowable 

Entries 




Column: 
16 28 

31 

32 

Indexed 

Sequential 

P 

b 

b 

b 



S 

b 

b 

b 



D 

b 

b 

b 



F 

b 

b 

b 


By ADDROUT 

P 

R 

I 

I 


file 

S 

R 

I 

I 


Sequential 

P 

b 

A/P 

I 


by key 

s 

b 

A/P 

I 



D 

b 

A/P 

I 



F 

b 

A/P 

I 


Sequential 

P 

L 

A/P 

I 


within 

S 

L 

A/P 

I 


limits 

D 

L 

A/P 

I 



F 

L 

A/P 

I 


For record-address files, you can use the entries listed in Table 2-2. 

Table 2-2: Modes of Processing for Record Address Files 


File 

Organization 

Allowable 
Access Modes 

Allowable 

Entries 





Column: 

16 28 

31 

32 

Sequential 

or 

Direct 

Sequential 1 

R 

b 

b 

b 

Sequential 2 

R 

b 

I 

T 


1 Indicates a record-limits file 

2 Indicates an ADDROUT file 

For input or update chained files, you can use the entries listed in Table 2-3. 
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Table 2-3: Modes of Processing for Input or Update Chained Files 


File 

Organization 

Allowable 
Access Modes 

Allowable 

Entries 





Column: 

16 28 

31 

32 

Sequential 

Random, by 

C 

R 

b 

b 

or Direct 

relative record 
number 

F 

R 

b 

b 

Indexed 

Random, 

C 

R 

A/P 

I 


by key 

F 

R 

A/P 

I 


In the following example, the program accesses an indexed file as a demand file and three 
update chained files. 


Mode (LR) 

I Key length 



Type (I0UD) II 

Record address type (API) 


Addtn(AU) 


IDes (PSRCTD)11 

1 Organization (IT,1-9) 


1 Expand 


IIE0F (E) II 

IIOverflow indicator 


11 Share 


IllSeq (AD) II 

III Key location 


111 Rewnd 

File 

IMIFmt (FV) II 

III 1 Extension (EL) 


III 1 

name 

IIIIIBlk Rec II 

III 1 1 Device Symb Tape 

Core 

III IFile 

1 

Mill len len II 

III 1 Icode dev label 

index 

III Icond 

FI 

MINI 1 II 

III 1 II II 

1 

III II 


0 I i 121 3 I 4 I 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 



## ###### - # - ##-### #-## # #. . #-###.## 

FINDEX1 ID F 18 5AI 5 DISK 

FCHAIN1 UC F 24R DISK 

FINDEX2 UC F 24R 3AI 1 DISK 

FCHAIN2 UC F 24R DISK 

ZK-4472-85 
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2.5.12 Key Length 

Use columns 29 and 30 to specify Key length. Key length indicates one of the following: 

• The length in bytes of the index keys in an indexed file 

• The length in bytes of the index keys in a record-limits file 

• The length in bytes of the addresses in an ADDROUT file 

Column Allowable Explanation 

Number Values 

29,30 Blank Indicates a sequential, direct, or display file 

1-99 Specifies the length of the record key for an indexed file or 

a record-address file 

Rules 

• You must use a value of 6 for the length of the record addresses in an ADDROUT file. 

• Right-justify this entry. 

• Leading zeros can be omitted. 

In the following example, the program reads a chained indexed file. The length of the 
record key is 3. 


Mode (LR) 

I Key length 



Type (I0UD) II 

Record address type (API) 


Addtn(AU) 


IDes (PSRCTD)11 

lOrganization (IT,i-9) 


1 Expand 


IIE0F (E) II 

MOverflow indicator 


11 Share 


11ISeq (AD) II 

III Key location 


111 Rewnd 

File 

111IFnt (FV) II 

III 1 Extension (EL) 


III 1 

name 

IIIIIBlk Rec II 

III 1 1 Device Symb Tape 

Core 

III IFile 

1 

Mill len len II 

III 1 Icode dev label 

index 

III Icond 

FI 

linn i ii 

III 1 II II 

1 

III II 


0111213141516171 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


#* ###### - * - ##-### #-## # # . #-###,## . . 

FINDEX IC F 24R 3AI 1 DISK 

ZK-4473-85 
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2.5.13 Record Address Type 

Use column 31 to specify Record address type. Record address type helps define the mode of 


processing. 

Refer to Tables 2- 

-1 through 2-3 to select the correct value. 

Column 

Number 

Allowable 

Values 

Explanation 

31 

Blank 

Uses relative record numbers to process sequential and 
direct chained files, or reads records sequentially from an 
input or update file, or creates or adds records to a sequen¬ 
tial output file 


A 

Processes or loads indexed files according to the record 
keys in alphanumeric format 


P 

Processes or loads indexed files according to record keys in 
packed format 


I 

Processes the file according to an ADDROUT file, or iden¬ 
tifies an ADDROUT file 

2.5.14 File Organization or Additional I/O Area 

File organization specifies how records are arranged in a file. Additional I/O allows you to 
specify the number of I/O areas. Both attributes work in conjunction with the Mode of 
processing. Refer to Tables 2-1 through 2-3 to select the correct value. 

Column 

Number 

Allowable 

Values 

Explanation 

32 

Blank 

Indicates a sequential or direct file, using one I/O area 


I 

Indicates an indexed file 


T 

Indicates an ADDROUT file 


1-9 

Indicates the number of I/O areas for a sequential or direct 
file 


For sequential files, RPGII adds 1 to the Additional I/O area value you specify in column 
32. RPG II uses the value for Additional I/O to set the VAX RMS multiblock count in the 
Record Access Block (RAB). 

See the Guide to VAX/VMS File Applications for information about multiblock count and 
for optimizing file performance. 
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2.5.15 Overflow Indicators 


Use columns 33 and 34 to specify an Overflow indicator. You can use an overflow indicator 
to specify a page break before or after certain lines are printed. See Part I, Chapter 6 for 
information on overflow indicators. 


Column 

Number 

Allowable 

Values 

Explanation 

33,34 

Blank 

Specifies no overflow indicator 


OA-OG, OV 

Specifies an overflow indicator to condition output lines 
when an overflow occurs 

Rules 




• You can use an overflow indicator to condition only printer output files. 

• You can assign only one overflow indicator to a file. If you have more than one printer 
output file and you want to use an overflow indicator to condition each file, you must 
specify a unique overflow indicator for each file. 


2.5.16 Key Location 

Use columns 35 through 38 to specify Key location. Each record in an indexed file has a key 
field that VAX RMS uses to locate records. This key field can be anywhere in the record, 
but must be in the same location for each record in the file. Key location specifies where to 
find the key field in the record. 


Column 

Number 

Allowable 

Values 

Explanation 

35-38 

Blank 

Indicates that the file is not indexed 


1-9999 

Specifies the location of the key field 

Rules 



• Right-justify this entry. 



• Leading zeros can be omitted. 


2.5.17 Extension Code 

Use column 39 to specify the Extension code that causes RPGII to read either the Exten¬ 
sion or the Line Counter specification for more information about the file. You must com¬ 
plete an Extension specification for tables, arrays, and record-address files. You can 
complete a Line Counter specification for a printer output file. The Line Counter specifica¬ 
tion specifies the length of the printed page and defines the overflow line number. 
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Column Allowable 
Number Values 

39 Blank 

E 

L 


Explanation 


Specifies no Extension or Line Counter specification 

Causes RPG II to read the Extension specification for the 
file 

Causes RPG II to read the Line Counter specification for 
the file 


2.5.18 Device Code 

Use columns 40 through 46 to specify the Device code that indicates on what type of device 
the file is stored. Left justify this entry. 


Column 

Allowable 

Explanation 

Number 

Values 


40-46 

Blank 

Specifies the default disk device. 


DISKXXX 

Specifies a disk device where X is any character. Disk can 
be specified for sequential files but is required for indexed 
and direct files. Disk is the default device. 


TAPEXXX 

Specifies a tape device for sequential files only. X can be 
any character. 


PRINTXX 

Specifies a print device for an output file. X can be any 
character. 


TTYXXXX 

Specifies a terminal device for a display file or a sequen¬ 
tially processed input or update file. X can be any charac¬ 
ter. 


READXXX 

Specifies a card reader for sequentially processed input 
files. X can be any character. 

To use a card reader, you must specify I in column 15 and P, 
S, T, or D in column 16. Also, leave columns 28 through 38 
blank. 


If you specify a device name other than one of the allowable values, RPG II accepts it, but 
issues a warning message at compile time. RPG II assumes a disk device, unless you spec¬ 
ify D in column 15, in which case RPG II assumes a terminal (TTY) device. 
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2.5.19 Symbolic Device 

Use columns 47 through 52 to specify the Symbolic device. The Symbolic device can be a 
logical name for any device. RPGII uses the Symbolic device as the file name string. VAX 
RMS uses the file name string and the default file name string (the file name that appears 
in columns 7 through 14) as the default name of a file being processed for input or output 
operations. See Part I, Chapter 5 for information on how RPG II uses the Symbolic device 
field (columns 47 through 52) and the File name field (columns 7 through 14) to generate 
the VAX/VMS file specification. 

Column Allowable Explanation 

Number Values 

47-52 Any Represents the symbolic device 

character 

The symbolic device name can contain up to six characters. 


2.5.20 Tape Label 

Use column 53 to identify the label for a magnetic tape. 


Column 

Number 

Allowable 

Values 

Explanation 



53 

Blank 

Indicates that the magnetic tape 
VAX/VMS ANSI label 

has a 

standard 


S 

Indicates that the magnetic tape 
VAX/VMS ANSI label 

has a 

standard 


VAX/VMS can process only magnetic tapes with VAX/VMS ANSI labels. 

2.5.21 Core Index 

Use columns 60 through 65 to set the VAX RMS multibuffer count in the Record Access 
Block (RAB). See the Guide to VAXIVMS File Applications manual for information about 
multibuffer count and for optimizing file performance. 

Column Allowable Explanation 

Number Values 

60-65 Blank Specifies that the file is not indexed or that an indexed file 

has no Core index 

1-9999 Specifies the number of bytes to reserve for the Core index 
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Rules 

• RPGII divides the Core index value by 512 and rounds the value to the next highest 
integer, if necessary. For example, if the Core index is 513, the VAX RMS multibuffer 
count is 2. 

If the operation results in an integer that is greater than 127, RPG II uses 127 as the 
VAX RMS multibuffer count. 

• Right-justify this entry. 

• Leading zeros can be omitted. 

2.5.22 File Addition and Unordered Output 

Use column 66 to specify File addition and Unordered output. File addition and Unordered 
output determine how new records are added to a file. You can add records to sequential, 
direct, and indexed files that reside on disk. On tape, you must go to the logical end of the 
tape before adding records to a file; otherwise, new records would overwrite existing 
records. 

Column Allowable 

Number Values 

66 Blank, A, U 

For output files, you can choose one of the following entries: 

Entry Explanation 

Blank Creates an indexed file and adds records by primary key, or creates a sequen¬ 

tial or direct file. 

A Adds records to an existing indexed or direct file or to the end of an existing 

sequential file. When you use this option, you must also specify ADD in col¬ 
umns 16 through 18 of the Output specification. 

U Creates an indexed file and adds records in an unordered sequence. 

For input files, you can choose one of the following entries: 

Entry Explanation 

Blank Reads records from a file without adding new records or changing existing 

records. 

A Reads records from an indexed or direct file and allows you to add new 

records. When you use this option, you must also specify ADD in columns 16 
through 18 of the Output specification. 
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For update files, you can choose one of the following entries: 

Entry Explanation 

Blank Allows you to update the records in a file. 

A Allows you to update the records in, and add records to, an indexed or direct 

file. When you use this option, you must also specify ADD in columns 16 
through 18 of the Output specification. 

You cannot add records to an indexed file that is being processed by a record-address file. 

2.5.23 Expansion Factor 

When records are added to indexed files, they are placed in buckets. (Buckets hold the con¬ 
tents of records.) If you attempt to randomly add a record into a full bucket, VAX RMS 
causes the bucket to split. VAX RMS tries to keep half of the records in the original bucket 
and moves the other records to a newly created bucket. Each split record leaves behind a 
pointer to the new bucket. When the system searches for one of the records in the newly 
created bucket, it must first go to the bucket where the record previously resided, read the 
pointer, and then move to the bucket pointed to by the pointer. This pointer manipulation 
overhead can add up, taking time and wasting disk space. 

To prevent bucket splitting and improve search efficiency, use an Expansion factor when 
creating an indexed file to reserve bucket space for the records you write to an indexed file. 
Also, specify a bucket size that is a multiple of the disk cluster size. To show the disk clus¬ 
ter size, type the following: 

$ SHOW DEVICE device/FULL 

Use column 67 to specify the Expansion factor. 


Column 

Allowable 

Explanation 

Number 

Values 


67 

Blank or 0 

Completely fills a bucket 


1 (minimum) 

Sets index bucket fill size to 50% and sets data fill size to 



100% 


2 (average) 

Sets index bucket fill size to 50% and sets data fill size to 



75% 


3 (above avg) 

Sets index bucket fill size to 50% and sets data fill size to 



60% 


4 (maximum) 

Sets index bucket fill size to 50% and sets data fill size to 


50 % 
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Additional Information 

• If the records you want to add are distributed unevenly by their key values, then RMS 
must split the buckets. In this case, use an Expansion factor of zero. 

• Records having key values that are close in sequence, and records added to the end of 
the file, cause VAX RMS to split the buckets anyway. For these kinds of records, use 
an Expansion factor of zero. 

• For output or update indexed files that are being created, RMS uses the Expansion 
factor to set the data bucket fill size and index bucket fill size in the key Extended 
Attribute Block (XAB). RPGII multiplies the bucket size value by 512 and adjusts the 
result based on the percentages listed above. 

Table 2-4 shows how the values for Expansion factor and Block length set the values 
for the following VAX RMS parameters: 

- FAB$B_BKS (bucket size) 

- XAB$W_IFL (indexed bucket fill size) 

- XAB$W_DFL (data bucket fill size) 

See the VAX Record Management Services Reference Manual for information on these 
parameters. See the Guide to VAX/VMS File Applications for information on indexed 
bucket fill size (index_fill) and data bucket fill size (data_fill). 


Table 2-4: Expansion Factor and Block Length Values 


File 

Expansion 

Block 

Length 

FAB$B_BKS 

XAB$W_IFL 

XAB$W_DFL 

1 (minimal) 

1536 

3 

768 

1536 

2 (average) 

2048 

4 

1024 

1536 

3 (above average) 

1024 

2 

512 

614 

3 (above average) 

2048 

4 

1024 

1228 

4 (maximum) 

2000 

4 

1024 

1024 
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2.5.24 File Sharing 

Use column 68 to specify the file sharing requirements of the file. File sharing allows more 
than one program to access the records in a file at the same time. If more than one program 
tries to access the same record, the first program that accessed the record will be allowed to 
change it and 

• (S option) the record will be locked preventing access from other programs until the 
first program is finished with the record; 

• (R option) the record will be locked preventing update access from other programs, 
but will not be locked from programs attempting to read the record. 

However, on a CHAIN operation code, you can specify an indicator to be set on when a 
record is locked, allowing the program to proceed while the record is still locked. See Sec¬ 
tion II 3.7.1 for information on CHAIN indicators for locked records. 


Column 

Number 

Allowable 

Values 

Explanation 

68 

Blank 

Uses RMS default file sharing 


S 

Specifies file sharing 


R 

Specifies file sharing with the lock for writing option 

Rules 




• Column 68 must be blank for a display file (D in column 15 of the File Description 
specification) and for an ADDROUT file (T in column 32 of the File Description 
specification). 

• Specifying S or R in column 68 is valid for a sequential file only if the sequential file 
has fixed-format records (F in column 19 of the File Description specification) and 
with a record length of 512. 

Additional Information 

• Table 2-5 illustrates file sharing that is inherently specified as a result of the combi¬ 
nation of the entries in columns 15, 66, and 68 of the File Description specification. 
The File Description specification that specifies these entries is assumed to be the first 
to open the file. 


Specifications 
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LEGEND: 


Table 2-5: File Sharing 


Symbol 

Meaning 

b 

Blank 



Columns 



15 

66 

68 


File 

Type 

File 

Addition 

Share 

Explanation 

I 

b 

b 

Any number of programs with the same entries in these three columns 
can read the file simultaneously. Any program with a different entry in 
File Type or File Addition for this file will receive a file-locked error. 

I 

A 

b 

No other program is allowed simultaneous access to the file. Any other 
program will receive a file-locked error. 

0 

b,A,U 

b 


u 

b,A 

b 


I, 

b,A,U 

s, 

Any other program with an S or R in Share can access the file simulta¬ 

o, 

u 


R 

neously, unless the file is for output and the file does not specify A for 

File addition, in which case a new version of the file is created. Any 
other program with a blank in Share will receive a file-locked error. 


• RPG II does not set the SHR field of the FAB (File Access Block) for the file when 
Share is left blank. When you specify S in column 68, RPG II sets the SHR field to 
allow GET, PUT, DEL, and UPD access. When you specify R in column 68, RPG II also 
sets the RLK option. See the Guide to VAX/VMS File Applications for more informa¬ 
tion on file sharing. 
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2.5.25 Tape Rewind 

Use column 70 to specify Tape rewind that positions a tape according to the current 
conditions. 

Column Allowable 

Number Values 

70 Blank 

U or R 

N 
K 
L 

2.5.26 File Condition 

Use columns 71 and 72 to specify the File condition. File condition associates an external 
indicator with a file. External indicators control file access at run time. When you condi¬ 
tion the file with an external indicator, RPGII opens the file only when the external indica¬ 
tor is set on. You can use external indicators to condition primary and secondary input and 
update files, record-address files, and output files. You can condition a record-address file 
by using an external indicator only if the following conditions are met: 

• The record-address file is associated with a primary or secondary input or update file. 

• The same indicator (or no indicator) is used to condition the associated file. 

See Part I, Chapter 4 for more information on external indicators. 

Column Allowable Explanation 

Number Values 

71,72 Blank Indicates no external indicator for this file 

U1-U8 Names the external indicator that controls file access at 

run time 

When you condition a file with an external indicator, use the same indicator to condition 
calculations and output operations for the same file. 


Explanation 

Indicates either that the file does not reside on tape, or, if 
the file does reside on tape, that the tape will rewind when 
the file is opened and closed 

Rewinds the tape when the file is opened and when the file 
is closed 

Does not rewind the tape 

Rewinds the tape when the file is opened 

Rewinds the tape when the file is closed 
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2.5.27 Example 

In the following example, 

• Line 1020 describes a primary input file with fixed-record format. Each record is 96 
bytes. The file CICWMS resides on disk with a symbolic device of XXI. 

• Line 1030 describes a demand file for input with fixed-record format. Each record is 96 
bytes. The file CARD58 resides on disk with a symbolic device of XX2. The external 
indicator U1 must be set on if the file is to be opened. 

• Line 1040 describes a demand file for update with fixed-record format. Each record is 
190 bytes. The file ICM resides on disk with a symbolic device of XX4. 

• Line 1110 describes an output file with fixed-length records. Each record is 132 bytes. 
The output file CONTRL will be written to the printer whose symbolic device is XI1. 
The overflow indicator is specified to condition output lines when an overflow occurs. 


Mode (LR) 

I Key length 



Type (I0UD) 1 

1 Record address type (API) 


Addtn(AU) 


IDes (PSRCTD)I 

1 lOrganization (IT,1-9) 


1 Expand 


IIE0F (E) 1 

1 llOverflow indicator 


11 Share 


11 ISecj (AD) 1 

1 III Key location 


III Rewnd 

File 

IMIFmt <FV> 1 

Mill Extension (EL) 


III 1 

name 

IIIIIBlk Rec 1 

Mill 1 Device Symb Tape 

Core 

III IFile 

1 

Mill len len 1 

Mill Icode dev label 

index 

III Icond 

FI 

IIIIII 1 1 

Mill II 1 1 

1 

III II 

0 1 

1 1 2 

1 3 1 4 1 5 

1 i 

i 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

** 

######—#—##-### *—## # 

. #- 

-###.## .. 

01020FCICUMS 

IP F 96 

DISK XXI 



01030FCARD58 

ID F 96 

DISK XX2 


Ui 

01040FICM 

UD F 190 

DISK XX4 



OiliOFCONTRL 

0 F 132 

OF PRINTR Xli 
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2.6 Extension Specification 

The Extension specification allows you to give RPGII additional information about record- 
address files, tables, and arrays. See Part I, Chapter 5 for information about record-address 
files. See Part I, Chapter 7 for information about tables. See Part I, Chapter 8 for informa¬ 
tion about arrays. 
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In general, use the Extension specification to describe the following information about a 
table or array: 

• Name of the table or array 

• Number of entries per record 

• Number of entries per table or array 

• Length of each table entry or array element 

• Format of numeric data 

• Decimal position 

• Sequence of entries 

• Related tables or related arrays in alternating format 

If your program uses a record-address file, complete columns 11 through 26 to provide the 
following information: 

• Name of the record-address file 

• Data file associated with the record-address file 

If your program uses tables or arrays, the time you load the tables or arrays determines the 
columns you must complete. For compile-time tables and arrays, you must complete col¬ 
umns 19 through 57; for pre-execution-time tables and arrays, columns 11 through 57; and 
for execution-time arrays, columns 27 through 32 and columns 36 through 45. 


2.6.1 Extension Specification Format 

The format of the Extension specification is: 


- F = Format (PB) 

I-D = Decimal positions 

|| -S = Sequence (AD) 

III 


11lAlternating table or array 


From 

To 

Table 

EntEnt 

Lenl1Iname 

Len 

file 

file 

or 

perin 

of Fill 

of F 

name 

name 

array 

RecTbl 

EntIDI 

EntID 

1 

1 

name 

1 1 

1 MSI 

1 1 IS 


El I I I I I INI I 111+— Comments —+ 


! 0 \ 1 I 2 T 3 I 4 I 5 I 6 I 7 H 

!l 2345678901234567890123456789012345678901234567890123456789012345678901234567890 


ft. ... ft ft ft #- ft - ft - ftftftft ft - ftftftft 
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2.6.2 Specification Type 

Use column 6 to identify the type of specification for every program line. 

Column Allowable Explanation 

Number Values 

6 E Indicates that this program line is an Extension specifica¬ 

tion 


2.6.3 From File Name 

Use columns 11 through 18 to specify the From file name that identifies the name of the 
record-address file or the input file used to load a pre-execution-time table or array. 


Column 

Allowable 

Explanation 

Number 

Values 


11-18 

Blank 

Loads the table or array named in columns 27 through 32 
(Table or array name) at compile time, if columns 33 
through 35 (Entry per record) are completed. 

Loads the array at execution time if specified by the Input 
and/or Calculation specification and if columns 33 through 
35 are left blank. 

Rules 

Name 

Names a record-address file, if specified. Otherwise, 
names the table or array input file. RPGII uses this file to 
load the table or array at pre-execution time. 


• This file name must be the same file name you used in a File Description specification. 

• Left-justify this entry. 


2.6.4 To File Name 

Use columns 19 through 26 in connection with your entry in columns 11 through 18 (From 
file name). If you name a record-address file in columns 11 through 18, specify the name of 
the input or update file it processes in columns 19 through 26. 
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Column Allowable Explanation 

Number Values 

19-26 Blank Does not write the table or array file at the end of the pro¬ 

gram. 

File name Identifies the data file associated with the record-address 

file, if you use a record-address file. If you do not use a 
record-address file, this entry names the output file that 
receives the data from the table or array at the end of the 
program. 

Rules 

• This file name must be the same file name you used in the File Description 
specification. 

• If you want to write a table or an array to an output file at the end of the program, 
enter the file name in columns 19 through 26. 

• You cannot write an execution-time array to an output file. 

• Left-justify this entry. 

2.6.5 Table or Array Name 

Use columns 27 through 32 to name the table or array you want to use. 

Column Allowable Explanation 

Number Values 

27-32 Blank Indicates that the file named in columns 11 through 18 

(From file name) is a record-address file 

Name Identifies the name of the table or array 

Rules 

• A table name can be any string of three to six alphanumeric characters, beginning 
with TAB. Table names cannot contain embedded blanks. 

• An array name can be any string of one to six alphanumeric characters, beginning 
with an alphabetic character. Array names cannot begin with TAB and cannot con¬ 
tain embedded blanks. 

• If you use tables or arrays in alternating format, this entry describes the name of the 
main table or array. Identify the alternate table or array name in columns 46 through 
51. 

• Left-justify this entry. 
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2.6.6 Number of Entries in a Record 


Use columns 33 through 35 to specify the number of entries in a table or array input 
record. Complete this entry for compile-time and pre-execution-time tables and arrays. 

Column Allowable Explanation 

Number Values 

33-35 Blank Indicates a record-address file or an execution-time array 

1-999 Specifies the number of entries in a table or array input 

record 

Rules 

• All records except the last must have the same number of entries. The last record can 
have fewer entries to accommodate a number of entries that is not an even multiple of 
the defined number of entries in the record. 

• The first entry must begin in the first position of the record. 

• Leave no spaces between entries in a record. 

• Entries cannot span two records. 

• If you use tables or arrays in alternating format, each record must contain a corre¬ 
sponding entry. The entries from the main table or array and the corresponding 
entries from an alternate table or array are treated as one entry. 

• Right-justify this entry. 

• Leading zeros can be omitted. 


2.6.7 Number of Entries in a Table or Array 

Use columns 36 through 39 to specify the number of entries in a table or array and in an 
alternate table or array, if an alternate table or array is used. 


Column Allowable 

Number Values 

36-39 Blank 

1-9999 


Explanation 

Indicates that the file named in columns 11 through 18 
(From file name) is a record-address file 

Specifies the number of entries in a table or array 
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Rules 


• If a compile-time or pre-execution-time table or array is not completely full, RPG II 
fills the unused entries with blanks for alphanumeric data or zeros for numeric data. 
If you specify an entry in column 45 (Sequence) of the Extension specification, pre¬ 
execution-time and compile-time tables and arrays must be full (RPG II does not fill 
the short entries). 

• Right-justify this entry. 

• Leading zeros can be omitted. 


2.6.8 Length of Entry 

Use columns 40 through 42 to specify the Length of entry that defines the number of char¬ 
acter (alphanumeric or numeric) positions in each table or array entry. 

Column Allowable Explanation 

Number Values 

40—42 Blank Indicates that the file named in columns 11 through 18 

(From file name) is a record-address file 

1-999 Specifies the number of character positions (both alphanu¬ 

meric and numeric) in each table or array entry 

Rules 

• For an alphanumeric entry, the maximum number of characters is 999. 

• For a numeric entry, the maximum number of digits is 15. 

• For numeric data, the maximum number of digits in binary format is 9. 

• For compile-time arrays, the maximum length of an entry is 96, because this is the 
largest record that can be entered in the source program. 

• When you use table and arrays in alternating format, this entry specifies the length of 
the entry in the main table or array. 

• Because all entries in a table or array must be the same length, fill unused alphanu¬ 
meric character positions with blanks and fill numeric entries with zeros. 

• Right justify this entry. 

• Leading zeros can be omitted. 
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2.6.9 Format 


Use column 43 to specify how numeric data is stored. Data format can be one of the follow¬ 
ing three formats: 

• Overpunched decimal 

• Packed decimal 


• Binary 

Base your selection of format on the storage space available and the frequency of use. See 
Part II, Chapter 1 for more information on data formats. 


Column 

Number 

Allowable 

Values 

Explanation 

43 

Blank 

Specifies that numeric data is in overpunched decimal for¬ 
mat, or that the table or array contains alphanumeric 
data. If you do not specify a table or an array, a blank indi¬ 
cates that the file named in columns 11 through 18 (From 
file name) is a record-address file. 


P 

Specifies that numeric data is in packed decimal format. 
This format is valid only for pre-execution-time tables or 



arrays. 


B 

Specifies that numeric data is in binary format. This for¬ 
mat is valid only for pre-execution-time tables or arrays. 

2.6.10 Decimal Positions 


Use column 44 to specify Decimal positions that defines the number of positions to the 
right of the decimal point for numeric data in a table or array. 

Column 

Number 

Allowable 

Values 

Explanation 

44 

Blank 

Specifies a record-address file or indicates that the table or 
array, if used, contains alphanumeric data 


0-9 

Specifies the number of positions to the right of the deci¬ 
mal point for numeric data in a table or array 


You must specify zero for numeric data with no Decimal positions. 
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2.6.11 Sequence 

Use column 45 to specify the Sequence that defines the order of entries in a table or array. 
RPGII checks each entry for the order you specify. 


Column 

Allowable 

Explanation 

Number 

Values 


45 

Blank 

Specifies a record-address file, or indicates that the entries 
in a table or an array are unordered 


A 

Specifies that the entries in a table or array are in ascend¬ 
ing order 

Rules 

D 

Specifies that the entries in a table or array are in descend¬ 
ing order 


• Consecutive entries that are equal in value are considered to be in sequence. 

• When you use tables or arrays in alternating format, this entry specifies the sequence 
of the main table or array. 

• When you specify a sequence for a compile-time or pre-execution-time table or array, 
RPG II checks the sequence of the entries in a table or an array. If an entry in a com¬ 
pile-time table or array is out of sequence, RPG II reports a fatal error at compilation. 
If a pre-execution-time table or array is out of sequence, a run-time error occurs. 

• You must specify a sequence if you use an indicator to test for a HIGH or LOW condi¬ 
tion in a LOKUP operation associated with the table or array. See Part II, Chapter 3 
for information on LOKUP 

• You can specify a sequence for an execution-time array, but RPG II does not check the 
sequence. However, if the execution-time array is not in correct sequence and you 
specify a LOKUP operation with a HIGH or LOW condition, unpredictable results 
will occur. 


2.6.12 Alternate Table or Array 

Use columns 46 through 57 to define the name, entry length, data format, number of deci¬ 
mal positions, and sequence for an alternate table or array. If you specify a table, you must 
use another table as its alternate. If you specify an array, you must use another array as its 
alternate. The same rules for columns 27 through 45 apply to the entries in columns 46 
through 57. 


Specifications 2-45 



2.6.13 Comments 


Use columns 58 through 74 to document the program line. 

Column Allowable Explanation 

Number Values 

58-74 Any Documents the program line 

character 

2.6.14 Example 

The following example specifies 

• A pre-execution-time array to be loaded from the file TABLEF at start of program 
execution (line 40) 

• A compile-time table with an alternate table (line 50) 

• A compile-time array (line 60) 

• An execution-time array (line 70) 


-F = Format (PB) 

I -D = Decimal positions 

||-S = Sequence (AD) 

III 


11lAlternating table or array 
From To Table EntEnt Lenlllname Len 


file file 

name name 

I I 

E I I 


or perin of Fill 
array RecTbl EntIDII 
name I I I MSI 
I III INI 


of F 
EntID 
I IIS 

I 111+— Comments —+ 


01 i I 2 I 3 I 4 I 5 I 6 I 71 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


* 

# *—*—*- 

— #### #-#### 

40E TABLE1 

ARRAY1 4 8 

5 0 

50E 

TABLE2 4 8 

1 TABLE3 3 0 

60E 

ARRAY2 30 100 

1 

70E 

ARRAY3 30 

1 
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2.7 Line Counter Specification 

The default length for a page of printer output is 66 lines; the default overflow line is at line 
60. When the printer reaches the overflow line, RPGII sets the overflow indicator on. 

The Line Counter specification allows you to alter the default page format of a printer out¬ 
put file. You can use this specification to change both the number of lines on a page and the 
overflow line. 
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2.7.1 Line Counter Specification Format 

The format of the Line Counter specification is: 

Form length (i-112) 

File I FL (if Form length used) 

name I I Overflow line number (i-112) 

I I I I OL (if Overflow line used) 

LI I I I I 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## #-# #-# 
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2.7.2 Specification Type 

Use column 6 to identify the type of specification for every program line. 

Column Allowable Explanation 

Number Values 

6 L Indicates that this program line is a Line Counter specifi¬ 

cation 

2.7.3 File Name 

Use columns 7 through 14 to name the output file. 


Column 

Number 

Allowable 

Values 

Explanation 

7-14 

File name 

Identifies the name of the output file 

Rules 




• The output file must be described on the File Description specification with PRINTER 
in columns 40 through 46 (Device code) and L in column 39 (Extension). 

• Left-justify this entry. 

See Part II, Chapter 1 for information on naming files. 
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2.7.4 Form Length 

Use columns 15 through 17 to define the number of lines printed on a page. Once the 
printer reaches the last specified line, it skips to the next page and resumes printing. 


Column 

Allowable 

Explanation 

Number 

Values 


15-17 

1-112 

Defines the maximum number of lines that can be printed 
on a page 

Rules 




• This entry must be a numeric value. 

• Right-justify this entry. 

• Leading zeros can be omitted. 

2.7.5 FL 

If you specify an entry in columns 15 through 17 (Form length), you must enter FL in col¬ 
umns 18 and 19. This entry specifies that columns 15 through 17 define the Form length. 

Column Allowable Explanation 

Number Values 

18,19 FL Causes RPG II to use the Form length defined in columns 

15 through 17 

2.7.6 Overflow Line Number 

Use columns 20 through 22 to specify the Overflow line number. When the page reaches 
the overflow line, RPG II sets the overflow indicator on. 


Column 

Number 

Allowable 

Values 

Explanation 

20-22 

1-112 

Specifies the Overflow line number 

Rules 




• This entry must be equal to or less than the entry in columns 15 through 17 (Form 
length). 

• This entry must be a numeric value. 

• Right-justify this entry. 

• Leading zeros can be omitted. 
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2.7.7 OL 

If you specify an Overflow line number in columns 20 through 22 (Overflow line number), 
you must enter OL in columns 23 and 24. This entry specifies that columns 20 through 22 
define the Overflow line number. 

Column Allowable Explanation 

Number Values 

23,24 OL Causes RPGII to use the Overflow line number defined in 

columns 20 through 22. 

2.7.8 Example 

In the following example, the Form length is 100 lines and the Overflow line number is 
line 96. 

Form length (1-112) 

File I FL (if Form length used) 
name I I Overflow line number (1-112) 

I I I I 0L (if Overflow line used) 

LI I I I I 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## #—# * .... 

LINPUT 100FL 960L 
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2.8 Input Specification 

The Input specification describes the records in input and update files. Each record is fur¬ 
ther divided into fields. Columns 7 through 42 describe the file and its records. Columns 43 
through 74 describe the fields in each record. 

The Input specification also describes data structure statements and data structure sub¬ 
fields. See Section 2.8.4 for information on data structures. 

You must use an Input specification to describe each input or update file except for table 
input files and record-address files. 
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2.8.1 Input Specification Format 

The format of the Input specification is: 



Sequence (AA-ZZ, 01-99) 





1 

Number (i-N) 





1 

1 Optional (0) 

Decimal positions 


1 

II Record identifying indicator 

III 

1 

Control level 


1 

1 

1 

Match field 


1 

111+ Identifying codes + Format 

1 

1 

1 Fid rec rel 

File 

1 

III 1 II (PB) 

[Field 

1 

1 1 

name 

1 

III 1 C C Cl 1 Fie1d 

Iname 

1 

1 1 Field 

1 

1 

III 1 Z Z Zl 1 location 11 

1 

1 1 indicatrs 

II 

1 

ill Pos NDcPos NDcPos NDc IFr To 

II 

1 

1 1 + - 0 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## * #** #— *— *— .##—#—## # #####,,, p 
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2.8.2 Specification Type 

Use column 6 to identify the type of specification for every program line. 


Column 

Allowable 

Explanation 

Number 

Values 


6 

I 

Indicates that this program line is an Input specification 

2.8.3 File Name 


Use columns 7 through 14 to name the input or update file. 

Column 

Allowable 

Explanation 

Number 

Values 


7-14 

Rules 

File name 

Identifies the name of the input or update file 


• Use the same name you specified in the File Description specification. 

• If this column is blank, RPG II assumes that the information in this program line 
describes a field or record from the file named last. 

• Describe all the records and fields for one file before describing another file. 

• Left-justify this entry. 
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In the following example, EMPLOYEE is the name of the input file, and the fields NAME 
and ADDRES, each containing 20 characters, belong to each record in the file. 



Sequence (AA-ZZ, 01-99) 





1 

1 

1 

Number (1-N) 
lOptional (0) 

II Record identifying indicator 

Decimal positions 

1 Control level 


1 

1 

III 

111+ Identifying codes + 
III 1 1 

Format 

1 

1 

1 Match field 

1 1 Fid rec rel 

File 

1 

1 (PB) 

1 Field 

1 1 1 

name 

1 

III 1 C C Cl 

1 Fie1d 

Iname 

1 1 1 Field 

1 

1 

III 1 Z Z Zl 

1locationl1 

1 1 1 indicatrs 

II 

1 

III Pos NDcPos NDcPos NDc 

IFr To 

II 

1 1 1 + - 0 


0 I 1 I 2 I 3 I 4 I 516 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### * - *— #— . ##—#—## # #####,.. , 

IEMPL0YEEAA 

I 1 20 NAME 

I 21 41 ADDRES 
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2.8.4 Data Structures 

Data structures consist of a data structure statement and 0 or more data structure sub¬ 
fields. You must describe data structures on Input specifications. Data structures follow all 
Input specifications (including all modifier specifications) for records. 

You can use data structures to do the following: 

• Define one area of storage more than one way 

• Define subfields within a field or subfield 

• Reorganize fields in an Input record 

• Select the internal numeric data type for fields 

• Communicate information between programs with a local data area 
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2.8.4.1 Data Structure Statement 


Column 

Number 

Allowable 

Values 

Explanation 

7-12 

Data 

Structure 

Name 

Identifies the data structure. The data structure name, 
which is not required, can be a field defined on Input speci¬ 
fications or Calculation specifications or defined nowhere 
else in the program. 

18 

U 

Optional. Identifies this data structure as the local data 
area. 

19-20 

DS 

Specifies a data structure. 

48-51 

1-9999 

Columns 48 through 51 may optionally contain the data 
structure length. 

Rules 




• The data structure name can appear on only one data structure specification, cannot 
be a look-ahead field, and can be specified anywhere a character field is allowed. 

• The length of the data structure is one of the following: 

1. The length specified in the Input specification, if the data structure name is an 
Input field 

2. The length specified in positions 48 through 51 of the data structure statement 

3. The highest To position (end position) of a subfield within a data structure, if the 
data structure name is not an Input field 

• The length computed by the To position must be less than or equal to the length speci¬ 
fied in 1 or 2 above. 

• Any length on a Calculation specification must match the largest value specified in 1 
or 2 above. 

• Because it is possible to specify the length of a single data structure in all three of the 
above ways in a single RPG II program, a compiler diagnostic will be given for any 
length conflicts. This will not occur if the length in columns 48 through 51 exceeds the 
highest To position for any subfield in the data structure. 

2.8.4.2 Data Structure Subfields 

Data structure subfields are described in columns 43 to 58. They are defined as on any 
other Input field specification. See Section 2.8.11 through 2.8.14 for those field specifica¬ 
tion requirements. 
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The field location start and end positions are relative to the beginning of the data struc¬ 
ture, not to the beginning of the data record. 

Rules 

• All columns except columns 43 through 58 must be left blank. 

• The subfield name can be the same as a field defined on an Input specification or a 
Calculation specification. 

• Subfields can be used as factor 1, factor 2, or the result field of a Calculation specifica¬ 
tion or as Output fields. 

• The same subfield name cannot be used in more than one data structure. 

• A data structure name cannot be used as a subfield name in another data structure. 

• Numeric subfields must contain numeric data when used in CHAIN, LOKUP, COMP, 
editing operations, or arithmetic operations. 

• If arrays are specified as subfields, the length specified must equal the amount of stor¬ 
age required to store the entire array. 

• A data structure subfield can not be an indicator (*IN field) or a UDATE field. 

• Overlapping subfields cannot be used in the same calculation in such a way that the 
result field overlaps either factor 1 or factor 2. If either factor 1, factor 2, or the result 
field references a subfield in a data structure that is an entire array or an array with a 
variable index, then that array is used to determine whether overlap exists. The same 
array name can be referenced in the appropriate factors of a Calculation specification 
without violating the overlap rule. 

• Any subfield previously defined in an Input record must agree in length (in digits), 
and in decimal positions. If the numeric datatype is different from what was specified 
in an Input record, the length (in digits) must still agree. 

• Any subfield defined more than once in the same data structure must be defined with 
the same datatype and start position, the same length, and the same decimal posi¬ 
tions, in the data structure. 

• Neither data structures nor data structure subfields can be individual array 
elements. 

• All entries for a data structure statement and its data structure subfields must appear 
together; they cannot be mixed with entries for other data structures. 

• A data structure statement and a data structure subfield cannot have the same name. 
See Section 2.8.15 for examples of using data structures. 


Specifications 2-53 



2.8.4.3 Local Data Area 

The RPGII local data area is a data structure of up to 512 bytes used as a means of commu¬ 
nicating information from one RPG II program to another. In addition, the RPG II local 
data area can be manipulated (read or written) at DCL command level or from a program 
written in another language. 

To specify a local data area, a data structure must have a U in column 18 on the I specs. The 
data structure need not have a name. Only the first 512 bytes of the data structure are 
loaded at program start and written out at program exit. At most, one data structure may 
have a U in column 18. 

The RPG II local data area is implemented with VMS DCL symbols (see the VAX/VMS 
DCL Dictionary for examples of manipulating DCL symbols). The following 4 symbols are 
used and correspond to the indicated bytes within a data structure with U in column 18: 

RPG$LDA1 1-128 

RPG$LDA2 129-256 

RPG$LDA3 257-384 

RPG$LDA4 385-512 

2.8.5 Sequence 

Use columns 15 and 16 to specify the Sequence that defines the ordering sequence of the 
record types in a file (for example, distinguishing employee name records from employee 
badge number records). RPG II does not order records according to sequence; rather, it 
checks the sequence of records in the input or update file. 


Column 

Number 

Allowable 

Values 

Explanation 

15,16 

Any two 

alphabetic 

characters 

Performs no sequence checking for this record. You can use 
any two letters from AA through ZZ, for example, BB, ZA, 
or DE. You must specify an alphabetic sequence for 
chained and demand files and look-ahead fields. 


Blanks 

Specifies no sequence checking for this record. 


Any 

two-digit 

number 

Assigns a sequence number to a record. You can use any 
two numbers from 01 to 99; however, you must use 
sequence codes in ascending order, beginning with 01. 


RPG II does not require that all Input specifications in alphabetic sequence appear before 
those Input specifications in numeric sequence. 
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2.8.6 Number 


If you assigned a numeric sequence code in columns 15 and 16, use column 17 to indicate 
the number of records in a record type. 


Column 

Number 

Allowable 

Values 

Explanation 

17 

1 

Specifies that there is only one record of this type 


N 

Specifies that there can be more than one record of this 
type 


Leave this column blank if you specified an alphabetic sequence in columns 15 and 16. 

2.8.7 Option 

If you assigned a numeric sequence code in columns 15 and 16, you can use column 18 to 
specify whether a record of that type must be present to continue processing records. 

Column Allowable Explanation 

Number Values 

18 Blank Specifies that a record of that type must be present 

O Specifies that a record of that type is optional 

Leave this column blank, if you specified an alphabetic sequence in columns 15 and 16. 

2.8.8 Record-Identifying Indicator 

Specifying an indicator in columns 19 and 20 associates the indicator with a particular 
record type. When RPGII processes a record of the type you specify for this program line, it 
also sets on the indicator, which remains on until after detail-time output. Then, RPG II 
sets off all indicators used as record-identifying indicators. See Part I, Chapter 4 for more 
information. 
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Column 

Number 

Allowable 

Values 

Explanation 

19,20 

Blank 

Specifies not to set on an indicator when RPG II processes 
a record of the type you specify. 


01-99 

Specifies a record-identifying indicator. 


L1-L9 

Specifies a control-level indicator. When RPG II sets on 
this type of indicator, it does not automatically set on 
lower-level control-level indicators. 


H1-H9 

Specifies a halt indicator. 


LR 

Specifies a last-record indicator. 


** 

Specifies that the fields described on the subsequent pro¬ 
gram lines are look-ahead fields. 


DS 

Specifies a data structure. 


Look-ahead fields allow you to 

• Determine when the last record of a control group is processed 

• Extend the matching-field processing capability 

Normally, RPGII processes one record at a time. The data from the record currently being 
processed is available. With look-ahead fields, you can evaluate the data from the next 
record to be processed and then determine which operation to perform. 

Any or all of the fields in a file can be specified as look-ahead fields. The description applies 
to all records regardless of their record type. 

To specify a field as a look-ahead field, you must enter ** in columns 19 and 20 of the Input 
specification. Also, you must specify an alphabetic sequence in columns 15 and 16 of the 
Input specification. All other columns must be blank. Then, on the next program line, 
enter the field name, as shown in the following example: 

Sequence (AA-ZZ, 01-99) 

I Number (i-N) 

I lOptional (0) Decimal positions 

I IIRecord identifying indicator I Control level 
I III II Match field 



1 

III 

+ Identifying codes + 

Format 

1 

1 

1 

Fid rec rel 

File 

1 

III 

1 1 

1 (PB) 

1 Fie 1 d 

1 

1 

1 

name 

1 

III 

1 C C Cl 

1 Fie 1d 

Iname 

1 

1 

1 Field 

1 

1 

III 

1 Z Z Zl 

1 location 

11 

1 

1 

1 indicatrs 

II 

1 

111 

Pos NDcPos NDcPos NDc 

IFr To 

11 

1 

1 

1 + - 0 


0 1 1 1 
123456789012345678901 

2 

23456: 

1 

78901 

3 

23456 

1 4 1 5 1 

7890123456789012345678901 

6 

23456 

1 7 1 

78901234567890 


## # ### #— # — # — .##—*—## ###### .... 

IEMPLOYEEAA Oi 

I i 20 NAME 

I BB *# 

I 21 25 BADGE 

ZK-4481-85 
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When using look-ahead fields, observe the following rules: 

• Look-ahead fields can be used only with input or update primary or secondary files. 

• For input files, look-ahead fields apply to the next record in the file. 

• For update files, look-ahead fields apply only to the next record in the file if the cur¬ 
rent record being processed was read from another file. Therefore, if you are using 
only one file, the look-ahead field is the current record being processed. 

• Look-ahead fields can be specified only once in a file. 

• Look-ahead fields cannot be the only record in the file. 

• As RPGII processes the last record, it fills any look-ahead fields with 9s. In this case, if 
the field is ten characters long, it will contain the data 9999999999. 

• Columns 59 through 70 must be blank on Input specifications describing look-ahead 
fields. 

• You cannot specify Blank after (B in column 39 of the Output specification) for look¬ 
ahead fields. 

• A look-ahead field cannot be used as a Result field in a Calculation specification. 

2.8.9 Record Identification Codes 

Use columns 21 through 41 to define a record type and to specify the code that indicates 
how to identify it. You can subdivide these columns into three subsets (columns 21 through 
27, 28 through 34, and 35 through 41), each defining a different code. 

If you use more than one subset, the record must satisfy all record identification codes. 
Used in this way, the codes form an AND relationship. If RPG II cannot identify a record 
according to the identification codes of all the records in a file, it issues a run-time error. 

If there is only one record type for a file, you can leave these columns blank. Also, you can 
leave these columns blank when describing the last record type in a file. This defines a 
record type to catch all records that do not fall into any of the record types you previously 
described. 

RPG II checks records for a record type in the order in which you specify them on the Input 
specification. 
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2.8.9.1 Position 

Use columns 21 though 24, 28 through 31, and 35 through 38 to define the Position that 
specifies where to look for the identification code in the input record. 

Column Allowable Explanation 

Number Values 

21-24 Blank Indicates that there is no record identification code. In this 

28-31 case, make sure that the corresponding Not, character (C), 

35-38 zone (Z) or digit (D) portion, and the character columns are 

blank. 

1-9999 Defines the position of the character you specify in col¬ 

umns 27, 34, and 41. For example, the number in columns 
28 through 31 specifies the position of the character in col¬ 
umn 34. 

Rules 

• Right-justify this entry. 

• Leading zeros can be omitted. 

2.8.9.2 Not 

Use columns 25,32, and 39 to specify whether an identification code must be present in the 
input record. 

Column Allowable Explanation 

Number Values 

25,32,39 Blank Indicates that the identification code you specify in the 

next two columns (26 and 27, 33 and 34, and 40 and 41) 
must be present to identify a record type. For example, if 
column 32 is left blank, the identification code in columns 
33 and 34 must be present. 

N Indicates that the identification code must not be present 

to identify a record type. For example, if you specify N in 
column 39, the identification code in columns 40 and 41 
must not be present. 

2.8.9.3 CZD Portion 

Use columns 26,33, and 40 to specify what portion of the character to use when identifying 
a record code. You can use the character (C), zone (Z), or digit (D) portion of the character. 
Many characters have either the same zone or digit portion. To distinguish between zone 
and digit portions, you must use their EBCDIC equivalent. See Appendix A for the ASCII 
character set and their corresponding EBCDIC zone and digit codes. 
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Column Allowable Explanation 

Number Values 


26,33,40 Blank 

C 

Z 

D 


Indicates that there is no record identification code. Its cor¬ 
responding Position, Not, and Character columns must be 
left blank. 

Causes RPG II to use the entire character to identify the 
record. 

Causes RPG II to use the EBCDIC zone portion to identify 
the record. 

Causes RPG II to use the EBCDIC digit portion to identify 
the record. 


2.8.9.4 Character 

Use columns 27, 34, and 41 to specify the identification character for the input record. 

Column Allowable Explanation 

Number Values 

27,34,41 Any Specifies the character part of the identification code 

character 

In the following example: 

• I in column 6 specifies that this program line is an Input specification. 

• EMPLOYEE in columns 7 through 14 names the input file. This file contains the 
name, address, and telephone number for each employee. 

• The characters AA in columns 15 and 16 specify no sequence checking. 

• RPG II sets on the indicator you specified in columns 19 and 20 (05) after it reads a 
record that matches the identification codes defined in columns 21 through 41. 

There are three parts to the code that identifies this record type: 

1. Position 1 must contain the character A. 

2. Position 31 must contain the character C. 

3. Position 123 must not contain a character with an EBCDIC digit portion of the 
number 6. This includes the characters F, O, W, 6, f, o, and w. 
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Sequence (AA-ZZ, Oi-99) 



1 Number (i-N) 

1 1 Optional (0) 

1 II Record identifying indicator 

Decimal positions 

1 Control level 


i hi 

1111+ Identifying codes + 

1 III 1 1 

Format 

1 

1 

1 Match field 

1 1 Fid rec rel 

File 

1 (PB) 

1 Field 

1 1 1 

name 

1 III 1 C C Cl 

1 Field 

Iname 

1 1 1 Field 

1 

1 III 1 Z Z Zl 

1 location 11 

1 1 1 indicatrs 

II 

1 111 Pos NDcPos NDcPos NDc 

IFr To 

II 

1 1 1 + - 0 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### # - # - #- .##-#-## ######,,,. 

IEHPLOYEEAA 05 i CA 31 CC 123ND6 


ZK-4482-85 


2.8.10 AND/OR 

Use columns 14 through 16 to enter AND or columns 14 and 15 to enter OR that associates 
two program lines to specify an identification code. 

AND specifies that the identification codes in two program lines must be matched in order 
to identify the record and to set on the record-identifying indicator, if one is specified. 


OR specifies that the identification code in either program line must be matched in order to 
identify the record and to set on the record-identifying indicator, if one is specified. 


Column 

Number 

Allowable 

Values 

Explanation 

14-16 

AND 

Specifies an AND relationship between the identification 
codes on this program line and the previous program line 

14,15 

OR 

Specifies an OR relationship between the record identifi¬ 
cation codes on this program line and the previous pro¬ 
gram line 

Rules 




• If you use AND, columns 7 through 13 and 17 through 20 must be left blank. 

• If you use OR, columns 7 through 13 and 16 through 18 must be left blank. 

• You can enter a record-identifying indicator in columns 19 and 20 in an OR line. If you 
leave columns 19 and 20 blank, the record-identifying indicator in the preceding pro¬ 
gram line also applies to this program line. 
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In the following example, there are four characters that identify a record type in 
EMPLOYEE: 

1. Position 1 must contain the character A. 

2. Position 31 must contain the character C. 

3. Position 1111 must contain the character zero. 

4. Position 123 must not contain the character 6. 

The record must meet all the conditions in both program lines before RPG II sets on the 
indicator (05). 

RPG II identifies a record type in the file RETIRED if position 1 contains the character I 
and position 31 contains the character D, or if position 123 does not contain the character 
6. The record must meet the conditions defined in either program line before RPG II sets on 
the indicator (06). 

Sequence (AA-ZZ, 01-99) 



1 

Number (1-N) 




1 

lOptional (0) 

Decimal positions 


1 

II Record identifying indicator 

1 

Control level 


1 

111 

1 

1 Match field 


1 

111+ Identifying codes + Format 

1 

1 1 Fid rec rel 

File 

1 

III 1 II (PB) 

IField 

1 1 1 

name 

1 

III 1 C C Cl IField 

Iname 

1 1 1 Field 

1 

1 

III 1 Z Z Zl 1 location 11 

1 1 1 indicatrs 

II 

1 

III Pos NDcPos NDcPos NDc IFr To 

II 

1 1 1 + - 0 

o 1 

1 

1 2 1 3 1 4 1 

5 

1 6 1 7 II 

|l 234-56789012345678901234567890123456789012345678901234567890123456789012345678901 

#* 

# 

*## *— *— *— , ##—#— 

-## 



IEMPLOYEEAA 05 i CA 31 CC 123NC6 

I AND 1111 CO 

IRETIRED AA 06 1 Cl 31 CD 

I OR 123NC6 

ZK-4483-85 


2.8.11 Format 

Use columns 7 through 41 to describe the file and the records in the file. Use columns 43 
through 75 to describe the fields of each record. Field descriptions must begin one line 
below the file and record description. Use a separate line to describe each field you plan to 
use. 

If a field contains numeric data, use column 43 to specify its format. You can specify 
overpunched decimal, packed decimal, or binary format. See Part II, Chapter 1 for infor¬ 
mation on data formats. 
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Column Allowable Explanation 

Number Values 

43 Blank Indicates that the field contains either alphanumeric 

characters or numeric data in overpunched decimal for¬ 
mat 

P Indicates that numeric data is in packed decimal format 

B Indicates that numeric data is in binary format 

See Part II, Chapter 1 for information on numeric data types. 

2.8.12 Field Locations From and To 

You define the fields of a record by specifying their location. Use columns 44 through 47 to 
specify the beginning character position of the field. Use columns 48 through 51 to specify 
the ending character position of the field. 


Column 

Allowable 

Explanation 

Number 

Values 


44-47 

1-9999 

Specifies the beginning character position of the field 

48-51 

1-9999 

Specifies the ending character position of the field 

Rules 



• The maximum length of a field depends on the type of data it contains. The maximum 


field length of overpunched decimal data is 15. The field length of binary data can be 2 
or 4. The maximum field length of packed decimal data is 8. To determine the field 
length of packed decimal data, divide the number of digits by 2 and add 1, ignoring the 
remainder. For example, if the number of digits in packed decimal data is 9, the 
length is 5. The maximum field length of alphanumeric data is 9999. 

• Fields can overlap if you give each field a different name. 

• Right-justify this entry. 

• Leading zeros can be omitted. 


2-62 


Specifications 



2.8.13 Decimal Positions 


If a field contains numeric data, use column 52 to specify the number of digits to the right of 


the decimal point. 


Column 

Number 

Allowable 

Values 

Explanation 

52 

Blank 

Indicates that this field contains alphanumeric data 


0-9 

Specifies the number of positions to the right of the deci¬ 
mal point 

Rules 




• You must specify a value in this column even if the numeric data has no decimal 
points. In this case, use zero. 

• The number of decimal positions must be less than or equal to the number of digits in 
the numeric field. 

If you specify 2 in this column and the field contains the data 12345, the field’s value is 
interpreted as 123.45. If you specify 4 in this column and the field contains the data 12345, 
the field’s value is interpreted as 1.2345. 


2.8.14 Field Name 

Use columns 53 through 58 to assign a name to the field you defined in columns 43 through 
52, or to specify the page number for PAGE. 


Column 

Number 

Allowable 

Values 

Explanation 

53-58 

Name 

Specifies the name of the field. The name can be a field 
name, array name, or array element. 


PAGE 

PAGE1-PAGE7 

Specifies a page number. See Chapter 6 for information on 
paging special words. 


*IN,*INxx 

Sets the specified indicator. See Chapter 4 for information. 

Rules 




• The field name can be any combination of six characters except for blanks or special 
characters, as long as the first character is a letter. See Part II, Chapter 1 for more 
information on user-defined names. 

• You cannot use the reserved words UDATE, UDAY, UMONTH, and UYEAR as a field 
name. 
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• Use a unique name for each field. If you use the same name to describe more than one 
field in the same record type, RPGII uses the field described last. 

• You can use the same name for fields of different record types as long as both fields are 
numeric with the same number of digits, or both fields are alphanumeric with the 
same length. 

• You can load an entire array from an input record by entering the array name in col¬ 
umns 53 through 58. If you do, columns 59 through 62 and 65 through 70 must be 
blank. 

• You can load an array element by entering the array name followed by a comma and 
an array index. 

To eliminate duplicate coding, use OR in columns 15 and 16 to define the same field names 
for different record types, as shown in the following example: 


Sequence (AA-ZZ, 01-99) 



1 Number (1-N) 

1 IQptional (0) 

1 II Record identifying indicator 

Decimal positions 

1 Control level 


i hi 

1 111+ Identifying codes + 

Format 

1 

1 

1 

1 

Match field 

1 Fid rec rel 

File 

1 III 1 1 

1 (PB) 

IField 

1 

1 1 

name 

1 III 1 C C Cl 

IField 

Iname 

1 

1 1 Field 

1 

1 III 1 Z Z Zl 

1 location 11 

1 

1 1 indicatrs 

II 

1 111 Pos NDcPos NDcPos NDc 

IFr To 

II 

1 

1 1 + - 0 


0 I i I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### # - * - #- .##-#-## ######..,, 


IEMPL0YEEAA 05 1 CA 

I OR 06 51 D6 

I 
I 
I 


1 30 NAME 
31 50 ADORES 
51 600PH0NE 


ZK-4484-85 

In this example, there are the same three fields (NAME, ADDRES, and PHONE) in two 
different types of records. In the first record type, there is the character A in position 1. In 
the second record type, there is the number 6 in position 51. The NAME field contains 
alphanumeric data: it begins in position 1 and ends in position 30. The ADDRES field con¬ 
tains alphanumeric data: it begins in position 31 and ends in position 50. The PHONE field 
contains numeric data with no decimal positions: it begins in position 51 and ends in posi¬ 
tion 60. 


2.8.15 Examples of Using Data Structures 

This section provides examples of using data structures in an RPG II program. 


2-64 Specifications 









2.8.15.1 Defining One Area of Storage More Than One Way 

The following example shows two fields that would normally require 1550 and 2400 bytes 
of storage without data structures. With data structures, however, these two fields are allo¬ 
cated using the same 2400 bytes of storage. In addition, several subfields within these 
fields are defined. The byte locations for each data structure subfield identify the locations, 
in a single data structure, where each data structure subfield is allocated. 

This example also demonstrates the optional length specification of the data structure on 
the data structure statement. If you omit the length of the data structure, RPGII computes 
it as described in Section 2.8.4.1. 


Sequence (AA-ZZ, 01-99) 



1 

Number (i-N) 




1 

lOptional (0) 

Decimal positions 


1 

II Record identifying indicator 

III 

1 

Control level 


1 

1 

1 Match field 


1 

111+ Identifying codes + Format 

1 

1 1 Fid rec rel 

File 

1 

III 1 II (PB) 

IField 

1 1 1 

name 

1 

Ml 1 C C Cl IField 

(name 

1 1 1 Field 

1 

1 

III 1 Z Z Zl 1 location)1 

1 1 1 indicatrs 

II 

1 

III Pos NDcPos NDcPos NDc IFr To 

II 

1 1 1 + - 0 

0 1 

12345678901234 

1 

51 

I 2 1 3 1 4 1 

&78901234567890123456789012345678901 

5 

234567! 

1 6 1 7 II 

B9012345678901234567890 

** 

* 

### #- #- #- .##—#— 

** 

###### .... 

IPERSNELL 

01 




I 

IMEDICAL 02 

I 

I DS 

^PERSONNEL RECORDS FIELDS 

I 

I 

I 

I 

I 

I 

I#MEDICAL RECORDS FIELDS 

I 

I 

I 

I 

I 

I 


11550 PREC 

12400 MREC 
2400 

11550 PREC 
1 50 CTGRYA 

50 100 CTGRYB 
100 150 CTGRYC 
150 800 BKGRND 
8001500 FTRUSE 

12400 MREC 
1 550 IMNLGY 
550 950 HMTLGY 
9501550 RADLGY 
15501950 XRAY 
19502400 0PR00M 


ZK-4485-85 
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2.8.15.2 Defining Subfields Within a Field or Subfield 

The following example shows how to divide a field into subfields. To do this, you must spec¬ 
ify the name of the field to be divided on the Input specification data structure statement. 


[011121 

12345678901234567890123456789012; 

3 1 4 1 5 1 6 1 

34567890123456789012345678901234567890123 

7 1 

546 6 78901 

## # *** *- *- 

ISURPLUS 01 

#— , ##—#—#* ###### .,. 

-- 

i 

IITEM DS 

1 12 ITEM 


I 

1 4 WHOSE# 


I 

5 8 AREA# 


I 

9 12 YEAR 


I 

11 11 DECADE 



ZK-4486-85 


2.8.15.3 Reorganizing Fields in an Input Record 

In the following example, a data structure is used to reorganize fields from an Input record. 
The first collection of fields describes the Input record field layout. The second collection of 
fields (in the data structure) describes how the fields are actually organized in memory 
when the program runs. 


[■011121 

12345678901234567890123456789012; 

3 1 4 

3456789012345678 

1 5 1 6 1 7 l| 

90123456789012345678901234567890 

## * ### # — # — 

IPART AA 

# — . ##-# 

— *# ## ####... . 

I 

1 

3 PN 

i 

4 

10 PNAME 

i 

11 

12 UH0USE 

I 

13 

20 C0LWEI 

I 

13 

17 COLOR 

i 

18 

20 HEIGHT 

I 

19 

200NWEIGH 

i 

IREGR0P DS 

21 

24 QTY 

I 

19 

21 PN 

I 

4 

10 PNAME 

I 

11 

17 UH0C0L 

I 

11 

12 UH0USE 

I 

13 

17 COLOR 

I 

1 

3 HEIGHT 

I 

23 

26 QTY 


ZK-4487-85 


#f 

| 

V 
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This example shows the difference between an Input field (the PART record) and a data 
structure subfield (the REGROP data structure). If either of the fields COLOR or WEIGHT 
is changed in a Calculation specification, no change will be reflected in the field COLWEI 
because COLOR and WEIGHT are not redefinitions of that field. In contrast, if either 
COLOR or WHOUSE is changed, WHOCOL will also change because COLOR is a redefini¬ 
tion of one portion of that field, and WHOUSE is a redefinition of another portion of that 
field. Changing WHOCOL changes COLOR and WHOUSE. Changing the value of 
COLWEI in a Calculation specification will not change COLOR or WEIGHT. 

2.8.15.4 Selecting the Internal Numeric Data Type for Fields 

The following example shows how to use a data structure to select a numeric data type that 
will be used internally. Choosing specific numeric data types can improve performance 
where numeric fields are passed as parameters in a CALL, because numeric data type con¬ 
version is then not needed at run time. In this example, the numeric data type is as indi¬ 
cated by the field name. 


01 1 I2I3I4I5I6I7I 

12345678901234567890123+56789012345678901234567890123456789012345678901234567890 


** * *** # - * - * - . ## - #-## ###### .... 

I DS 

I P i 30PACKED 

I B 4 50W0RD 

I B 6 90L0NGW0 

I 10 1400VERPU 

ZK-4488-85 

If you specify a numeric data type for a data structure subfield, RPGII does not automati¬ 
cally convert numerics to packed decimal. A numeric conversion is performed if you define 
a subfield with a numeric data type that is different from the Input field declaration. Arith¬ 
metic comparisons are done with the field maintaining the declared data type. Note that 
arithmetic (ADD/SUB/MULT/DIV) is still performed in packed decimal, and a conversion 
is done before performing any of the arithmetic operations. 

Where RTL routines are called with various numeric data types, you can use data struc¬ 
tures to declare the numeric data type so a conversion is not needed for the CALL. 

Note that data structures do not support floating point numeric data. 
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The example below shows several numeric fields defined in an input record, then redefined 
with different numeric data types in a data structure. Each field redefinition must agree in 
number of digits with any previous field definition. 


0 1 1121314 I 5 161 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### # — # — #— .*#—#—## ####*# .... 

IFILE BB 


I 

B 

1 

20IW0RD4 

I 

B 

11 

140IL0NG9 

I 

P 

21 

250IPACK9 

I 


31 

340I0VER4 

I 


41 

470I0VER7 

I 


51 

590I0VER9 

I 

DS 



I 


1 

40IU0RD4 

I 

P 

11 

150IL0NG9 

I 

B 

21 

240IPACK9 

I 

B 

31 

320I0VER4 

I 

P 

41 

440I0VER7 

I 

B 

51 

540I0VER9 
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Each field is named to highlight the number of digits assigned to them, as defined in the 
input record. For example, PACK9 is defined to be a 5 byte (9 digit) field in the input record. 
The data structure indicates that PACK9 will be stored internally in the data structure as 
a longword (4 bytes). OVER7 is defined to be a 7 byte (7 digit) field in the input record. The 
data structure indicates that OVER7 will be stored internally in the data structure as a 
packed field (4 bytes). In all cases, the number of digits for the field as defined on the input 
record must agree with the number of digits in any subsequent field redefinition. 


2.8.15.5 Examples of Using Local Data Area 

The following example demonstrates use of a local data area. The program LDA is as 
follows: 


0 I 1 I 2 I 3 I 41 5 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FTTY D V 80 TTY 


I 

UDS 




I 



1 

15 NAME 

I 



16 

170AGE 

C 

NAME 

DSPLYTTY 



c 

AGE 

DSPLYTTY 



c 


MOVEL'S. 

Jones'NAME 


c 


Z-ADD29 

AGE 


c 


SET0N 


LR 
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The following commands load the local data area with a name and age. The name and age 
are modified in the program, and this information is written back to the local data area on 
exit. 

$ RPG$LDA1 = "K. Smith 
$ RPG$LDA1[15 >21 := "45" 

$ RUN LDA 
K ♦ Smith 
45 

$ SHOW SYMBOL RPG$LDA1 
RPG$LDA1 = "S. Jones 29" 

$ RUN LDA 
S ♦ Jones 
29 

The following example demonstrates use of a local data area which contains binary data. 
The program LDA_BINARY is as follows: 


0I1I2I3I4I5I6I7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


FTTY 

D V 

80 

TTY 


I 

UDS 




I 



1 

15 NAME 

I 



B 16 

170AGE 

C 

NAME 

DSPLYTTY 



C 

AGE 

DSPLYTTY 



c 


MOVEL'S. 

Jones'NAME 


c 


Z-ADD29 

AGE 


c 


SET0N 


LR 


ZK-4664 85 


The following commands load the local data area with a name and age. The name and age 
are modified in the program, and this information is written back to the local data area on 
exit. 


$ RPG$LDA1 = "K♦ Smith 
$ RPG$LDA1[15*8 tlGl = 45 
$ RUN LDA_BI NARY 
K * Smith 
45 

$ RUN LDA_BI NARY 
S ♦ Jones 
29 
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The following example demonstrates use of a local data area with 386 bytes of information. 
The program LDA_386 is as follows: 


01 1I2I3I4I5 I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


IDS386 UDS 

I 1 383 DATA1 

I 384 386 DATA2 

C MOVE 'abc' DATA2 

C SET0N LR 

ZK-4663-85 

The following commands display the information written to the local data area by the 
program: 

$ RUN LDA_386 

$ CHAR_384 = F$EXTRACT(127 >1 >RPG$LDA3) 

$ SHOW SYMBOL CHAR_384 
CHAR_384 = "a" 

$ SHOW SYMBOL RPG$LDA4 
RPG$LDA4 = "be" 

Note that in this example, the field DATA1 is spread over RPG$LDA1, RPG$LDA2 and 
RPG$LDA3. The field DATA2 is written to the last byte of RPG$LDA3 and the first 2 bytes 
ofRPG$LDA4. 

2.8.16 Control-Level Indicator 

Use columns 59 and 60 to specify control-level indicators. Control-level indicators cause 
RPGII to compare the contents of a field with the contents of the same field from a previous 
record. If the fields are not equal, a control break occurs and RPG II sets on the control- 
level indicator assigned to that field. 

You can use this type of indicator to condition input, calculation, and output operations. 

Column Allowable Explanation 

Number Values 

59,60 Blank Indicates that this field is not a control field 

L1-L9 Associates a control-level indicator with the field you spec¬ 

ify in columns 53 through 58 
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Rules 


• You can specify control-level indicators for primary and secondary files only. 

• You can assign control-level indicators in any order. 

• Control-level indicators are ranked from highest (L9) to lowest (LI). When a control 
break causes RPGII to set on a control-level indicator, all lower control-level indica¬ 
tors are set on. All control-level indicators are set off after detail-time output. 

• When you assign the same control-level indicator to more than one field, the fields are 
referred to as a split-control field. In this case, fields must be either all numeric or all 
alphanumeric and described on adjacent lines. Split-control fields do not have to be 
the same length. 

• Fields with different control-level indicators can overlap in a record. 

• You do not need to specify the same number of control fields for all record types. 

• RPG II initializes control fields to hexadecimal zeros. This usually causes a control 
break to occur on the first record with a control field. Because of this, RPG II bypasses 
total-time calculation and output operations for this cycle. 

• You cannot specify control-level indicators for binary data or look-ahead fields. Also, 
you cannot specify a control-level indicator when you specify an array name in col¬ 
umns 53 through 58. 

• RPG II ignores decimal positions and signs (positive and negative) when determining 
a control break. 

• Because field names are ignored, you can assign the same control level indicator to 
multiple fields with the same name. 

• If you assign the same control-level indicator to more than one field in different types 
of records, the fields must be either all numeric with the same number of digits or all 
alphanumeric with the same number of characters. 

• The total length of a split-control field must be the same length as other uses of the 
same control-level indicator. 

• If a control field contains packed decimal data, the zoned decimal length, which is two 
times the packed decimal length minus one, is considered the length of the field. 

See Section 2.8.18 for information about using a field-record-relation indicator with con¬ 
trol fields. 
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In the following example, each record in the file EMPLOYEE contains the same three 
fields: NAME, ADDRES, and DEPTNO. The length of NAME is 30 characters; the blank 
in column 52 indicates that the contents of the field are alphanumeric. The length of 
ADDRES is 20 characters. Both fields are assigned the same control-level indicator (L8), 
so they are split-control fields. DEPTNO contains more significant data and as such, is 
assigned a higher-level control-level indicator. When the contents of DEPTNO changes, 
RPGII sets on both control-level indicators (L9 and L8). 


Sequence (AA-ZZ, 01-99) 



1 Number (1-N) 

1 1 Optional (0) 

1 II Record identifying indicator 

Decimal positions 

1 Control level 


1 III 

1 111+ Identifying codes + 

1 III 1 1 

Format 

1 

1 

1 

1 

Match field 

1 Fid rec rel 

File 

1 (PB) 

1 Field 

1 

1 1 

name 

1 III 1 C C Cl 

1 Fie1d 

Iname 

1 

1 1 Field 

1 

1 III 1 Z Z Zl 

1locationl1 

1 

1 1 indicatrs 

II 

1 III Pos NDcPos NDcPos NDc 

IFr To 

11 

1 

1 1 + - 0 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** * *** * - * - # - . ##-#-## 


IEMPL0YEEAA 
I OR 

I 
I 
I 


05 1 CA 

99 123ND6 


31 CC 


1 30 NAME L8 
31 51 ADDRESL8 
123 1230DEPTN0L9 


ZK-4490-85 


2.8.17 Matching Fields 

Use columns 61 and 62 to specify matching fields. Matching fields tell RPG II to compare 
the fields in records from one or more files. When the contents of a field from a primary file 
match the contents of a field from a secondary file, RPG II sets on the matching-record 
indicator (MR). 


You can use the matching-record indicator to condition calculation and output operations. 

Column Allowable Explanation 

Number Values 

61,62 Blank Indicates that this field is not a matching field. 

M1-M9 Identifies a matching field. See Part I, Chapter 5 for infor¬ 

mation about matching fields and multifile processing. 

Rules 

• You can use matching fields with one file to perform sequence checking or with multi¬ 
ple files to control the order of processing records. See Part I, Chapter 5 for informa¬ 
tion on multifile processing. 
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You can compare only those fields from records in primary and secondary input and 
update files. 

You can compare up to nine different fields in a single record. 

If you specify more than one matching field for a record type, all the fields are logically 
concatenated and treated as one continuous field. The fields are combined according 
to descending sequence (M9 to Ml) of matching field values. 

The program performs sequence checking for all record types with matching field 
specifications. An error in sequence causes a run-time error and terminates the 
program. 

You must define the same number of matching fields and the same matching field val¬ 
ues (M1-M9) for all those records that contain matching fields. 

You can overlap matching fields in a single record. 

Whenever you use more than one matching code, all matching fields must match 
before RPGII sets on the matching-record indicator (MR). 

Matching fields assigned the same matching code (M1-M9) must be either both 
numeric with the same number of digits, or both alphanumeric with the same length. 

Not all files or all record types within one program must have matching fields. How¬ 
ever, at least one record type from each of two files must have matching fields if the 
files are to be matched. 

If the matching field contains packed data, the zoned decimal length, which is two 
times the packed length minus one, is considered the length of the matching field. It is 
valid to match a packed field in one record against a zoned decimal field in another if 
the digit lengths are identical. The length must always be odd, because the length of a 
packed field is always odd. 

The file sequence you specify in column 18 of the File Description specification must 
be the same for the files you compare — all ascending or descending. 

You can check the sequence of a single sequential file using M1-M9 codes to designate 
the order of sequence. If the file is out of sequence, a run-time error occurs. 

You cannot specify matching values for binary data and look-ahead fields. You cannot 
specify matching values when you specify an array name in columns 53 through 58. 

If you specify an alternate collating sequence, RPG II uses the alternate sequence 
when comparing the values in matching fields containing alphanumeric data. 

RPG II ignores field names, so fields from different record types can have the same 
name and match code. 
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• When you specify an ascending sequence check, RPGII initializes the matching value 
to hexadecimal zeros. When you specify a descending sequence check, RPG II initial¬ 
izes the matching value to hexadecimal FFs. RPG II initializes the matching value of 
a numeric field to zero. 

• RPG II compares matching fields containing numeric data based on their absolute 
values because decimal positions and signs are ignored. 

• Matching fields cannot be split: the same matching field value cannot be used more 
than once for one type of record. 

• When you specify a matching field value for a field without a field-record-relation 
indicator, you must specify all matching field values once without a field-record-rela¬ 
tion indicator. If all matching fields are not common to all records, use a dummy 
matching field. See Section 2.8.18 for information on using a field-record-relation 
indicator with matching fields. 

• Matching fields are independent of control-level indicators. 

See Part I, Chapter 5 for examples of matching fields. 

2.8.18 Field-Record-Relation Indicator 

Use columns 63 and 64 to specify Field-record-relation indicators that control the condi¬ 
tions under which RPG II extracts data from the input buffer into a field. These conditions 
include control breaks, matching records, halts, and external indicators. 

The most common use of a field-record-relation indicator is as a record-identifying indica¬ 
tor to group several different record types in an OR relationship and associate fields with a 
particular record type. You can also use field-record-relation indicators to extract data if a 
particular external indicator is on. 
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Column 

Allowable 

Explanation 

Number 

Values 


63,64 

Blank 

Indicates no field-record-relation indicator 


01-99 

Indicates that the field-record-relation indicator is a 
record-identifying indicator 


L1-L9 

Indicates that the field-record-relation indicator is a con¬ 
trol-level indicator 


MR 

Indicates that the field-record-relation indicator is the 
matching-record indicator 


U1-U8 

Indicates that the field-record-relation indicator is an 
external indicator 


H1-H9 

Indicates that the field-record-relation indicator is a halt 
indicator 


Rules 

The following rules apply to field-record-relation indicators used with control and match¬ 
ing fields: 

• You must specify control fields and matching fields without field-record-relation 
indicators before those fields with them. 

• When the field-record-relation indicator associated with a matching or control field is 
on, RPG II uses that field as the control or matching field for the record rather than 
the same control or matching field specified without a field-record-relation indicator. 
Otherwise, RPG II uses the control or matching field without the field-record-relation 
indicator. 

• When you have not defined an entire set of matching fields without a field-record- 
relation indicator, a full set of matching fields must be assigned to each field-record- 
relation indicator used with a matching field. 

• You must use the same field-record-relation indicator for split-control fields. You must 
describe the split-control fields on consecutive lines. 

• You must group control and matching fields that use field-record-relation indicators 
according to indicator. 

• Field-record-relation indicators for control and matching fields can be only 01 
through 99 or HI through H9 indicators. Also, the field-record-relation indicator for 
control and matching fields must be a record-identifying indicator specified on either 
the preceding record definition line, or in one of the lines in an OR relationship. 
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If you have two records of eight fields each, and the first seven fields are the same but the 
last field is different, you can use the record-identifying indicator as the field-record-rela¬ 
tion indicator to condition the field that is different, rather than defining all eight fields for 
both records. 

In the following example, the last two fields were conditioned with the same record-identi¬ 
fying indicators in lines 1 and 2. If the job code is 2, RPG II uses the bonus amount from 
positions 72 through 74. If the job code is not 2, RPG II uses the bonus amount from posi¬ 
tions 75 through 77. 



Sequence (AA-ZZ, 01-99) 

1 Number (1-N) 

1 lOptional (0) 

Decimal positions 


1 

IIRecord identifying indicator 

III 

1 

Control level 


1 

1 

1 

Match field 


1 

111+ Identifying codes + Format 

1 

1 

1 Fid rec rel 

File 

1 

III 1 II <PB) 

IField 

1 

1 1 

name 

1 

III 1 C C Cl IField 

Iname 

1 

1 1 Field 

1 

1 

III 1 Z Z Zl 1locationl1 

1 

1 1 indicatrs 

II 

1 

III Pos NDcPos NDcPos NDc IFr To 

11 

1 

1 1 + - 0 


0 I 1 I 2 I 3 I 4 I 5 I 6 I 7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # ### #— #— *— 

IEMPL0YEEAA 01 71 C2 

I OR 02 71NC2 

. ##—#■ 

—## 

I 

1 

10 FNAME 

I 

11 

12 MINIT 

I 

13 

33 LNAME 

I 

34 

54 ADDRES 

I 

55 

60 STATE 

I 

61 

700PH0NE 

I 

71 

710J0BCDE 

I 

72 

742B0NUS 

I 

75 

772B0NUS 


ZK-4491 -85 
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2.8.19 Field Indicators 


Use columns 65 through 70 to specify Field indicators. Field indicators check the condition 
of numeric or alphanumeric fields when they are extracted from the input record. Once 
checked, the field can be in one of three conditions: 

1. If the numeric field in columns 53 through 58 is greater than zero, the condition is 
positive and RPG II sets on the field indicator in columns 65 and 66. Otherwise, 
RPGII sets off the indicator. 

2. If the numeric field in columns 53 through 58 is less than zero, the condition is 
negative and RPG II sets on the field indicator in columns 67 and 68. Otherwise, 
RPG II sets off the indicator. 

3. If the numeric field in columns 53 through 58 is equal to zero, or if the alphanu¬ 
meric field in columns 53 through 58 contains blanks, the condition is null and 
RPG II sets on the field indicator in columns 69 and 70. Otherwise, RPG II sets off 


the indicator. 


Column 

Number 

Allowable 

Values 

Explanation 

65-70 

Blank 

Indicates no field indicators. 


01-99 

Associates a field indicator with a field. 


H1-H9 

Indicates that the field indicator is a halt indicator. Halt 
indicators check for errors in data. For example, you can 
specify a halt indicator to check for zeros in a numeric 
field. If RPG II processes the record and finds a zero in the 
field, it sets on the halt indicator that results in a run-time 
error. 

Rules 




• Use columns 65 through 70 to check numeric fields. 

• Use columns 69 and 70 to check alphanumeric fields. 

• You can use the same field indicator for more than one field in different record types. 
The status of the indicator depends on the record type last read. 

• Columns 65 through 70 must be blank when columns 53 through 58 contain an array 
without an index or look-ahead fields. 

• You can assign one or more field indicators to a numeric field. 
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2.9 Calculation Specification 

The Calculation specification allows you to describe the calculations you want to perform 
and to define their order in the following ways: 

• Entries in columns 7 through 17 control when a calculation is performed. 

• Entries in columns 18 through 53 describe the kind of calculation. 

• Entries in columns 54 through 59 specify which indicators the program sets on or off 
as a result of the calculation. 

There are two general rules: 

1. Specify each calculation on a single line; arrange the calculations in the order 
you want them executed. 

2. Specify detail-time calculations first, then total-time calculations, and, finally, 
calculations in subroutines. 

2.9.1 Calculation Specification Format 

The format of the Calculation specification is: 


Field length 


Control level 


1 

Decimal positions 

1 


i 

IHalf adjust (H) 

1 Indicators 

Operation 

1 

1 1 

1 1 

1 

1 

11 Resulting 

1 1 Factor 

1 Factor 

Resu1t1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

ll> < = +- Comments —+ 

0 1112 

1 3 1 

4 1 

5 1 6 1 7 II 

|123456789012345678901234567890123456789012345678901234567890123456789012345678901 


## # # # # # ### # # # 
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2.9.2 Specification Type 

Use column 6 to identify the type of specification for every program line. 

Column Allowable Explanation 

Number Values 

6 C Indicates that this program line is a Calculation specifica¬ 

tion. 
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2.9.3 Control Level 


Use columns 7 and 8 to indicate whether the calculation is performed at detail time, is 
performed at total time, or is part of a subroutine. 


Column Allowable 

Number Values 

7,8 Blank 

LO 

L1-L9 


LR 


SR 

AN or OR 


Explanation 


Performs the calculation at detail time, or indicates that 
the program line is part of a subroutine. 

Performs the calculation at total time for each program 
cycle. 

Performs the calculation at total time after a control break 
occurs, or when you use the SETON operation to set on the 
control-level indicator, or when the indicator is set on as a 
record-identifying indicator, or when the indicator is set 
on as a resulting indicator in a calculation. 

Performs the calculation at total time after the program 
processes the last record, or when you use the SETON 
operation to set on the LR (last-record) indicator, or when 
the indicator is set on as a record-identifying indicator, or 
when the indicator is set on as a resulting indicator in a 
calculation. 

Indicates that the calculation is part of a subroutine. 

Establishes a relationship between two program lines. If 
you use AN, the conditions for the indicators in both pro¬ 
gram lines must be satisfied before RPG II executes the 
calculation. If you use OR, the conditions for the indicators 
in one program line or the other must be satisfied before 
RPG II executes the calculation. 


You can use an unlimited number of AN or OR program lines with up to three indicators on 
each line to condition a single calculation. The last line in an AN or OR relationship speci¬ 
fies the calculation. 


Additional Information 


You can specify the following declarative statements in total-time calculations and option¬ 
ally leave columns 7 and 8 blank: 

• EXTRN 

• GIVNG 


Specifications 2—79 



• PARM 

• PARMD 

• PARMV 

• PLIST 

• TAG 

In the following example, the LI, L2, L3, and LR control-level indicators perform calcula¬ 
tions at total time after a control break occurs or when the SETON operation code sets on 
the indicator. 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

Field length 

1 Decimal positions 

1 (Half adjust (H) 

1 II 

1 II Resulting 

Result 1 II indicators 
field 1 11+ - 0 

1 1 11> < = +- Comments —+ 

0 1 

11234567890123^ 

i 1 

1-567890123- 

2 13 1 

45678901234567890 

4 1 5 1 6 1 7 11 

1234567890123456789012345678901234567890 

## * 

* 

# * 

# #—### # # # 

c# 

Total calculations: 


c* 




CL1 


SET0F 

LRL9L8 

CL1 


SET0F 

L7L6L5 

CLi 


SET0F 

L4L3L2 

CLi 

'L i' 

DSPLYS 


CLi 


SET0F 

L2L3LR 

C# 




CLi 


EXSR HILLS 


CLi 

PELHAM 

TAG 


C# 




CLi 

'L 2' 

DSPLYS 


CL3 

'L 3' 

DSPLYS 


C# 




CL3 


EXSR CARROL 


CLi 


GOTO PETERB 


C# 




CLi 

'L 4' 

DSPLYS 


CL2 

6 

COMP BERRY 

313233 

CLR 


SET0F 

24 
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2.9.4 Indicators 

Use indicators in columns 10,11,13,14,16, and 17 to condition the calculations you spec¬ 
ify in columns 28 and 32. You can specify up to three indicators per program line; precede 
the indicator with N to cause RPGII to perform the calculation only when the indicator is 
not on. Use columns 9 through 11 to describe the first indicator, columns 12 through 14 to 
describe the second, and columns 15 through 17 to describe the third. Using the indicators 
this way forms an AND relationship. 


Column 

Number 

Allowable 

Values 

Explanation 

10-11 

13-14 

16-17 

Blank 

Performs the calculation whenever the conditions speci¬ 
fied in columns 7 and 8 are satisfied. 


Indicator 

Performs the calculation when the conditions for the indi¬ 
cator are met. 

9,12,15 

N 

Causes RPG II to perform the calculation only when the 
indicators associated with N are not set on. N in column 9 
conditions the indicator in columns 10 and 11. N in column 
12 conditions the indicator in columns 13 and 14. N in col¬ 
umn 15 conditions the indicator in columns 16 and 17. 


Additional Information 

• You can use one of the following indicators in columns 10 and 11, 13 and 14, and 16 
and 17: 

- Record-identifying (01-99) 

- Control-level (L1-L9) 

- Last-record (LR) 

- Matching-record (MR) 

- Halt indicator (H1-H9) 

- External (U1-U8) 

- Overflow (OA-OG, and OV) 

- K indicators (KA-KZ, and K0-K9) 

• RPG II performs total calculations for a control break before performing detail-time 
calculations for the record that causes the control break. 
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• Halt indicators in columns 10,11,13,14,16, and 17 cause RPGII to bypass the opera¬ 
tion when it finds an error in the input data or in a previous calculation. RPG II 
processes the record that causes the error before stopping your program. In this case, 
the record in error could cause an error in calculation before your program 
terminated. 

• Depending on the relationship between indicators in columns 7 and 8 and columns 9 
through 17, the actions RPG II takes will vary as follows: 

- When you specify a control-level indicator in columns 7 and 8 and a matching- 
record indicator in columns 9 through 17, MR indicates the result of matching the 
previous record rather than the record just read that caused a control break. RPG II 
executes all the operations conditioned by control-level indicators before determin¬ 
ing the matching condition of the record just read. 

- When you use a control-level indicator in columns 10,11,13,14,16, and 17 instead 
of columns 7 and 8 of the Calculation specification, RPG II performs the calculation 
on the first record of a new control group at detail time. 

- In a single program cycle, RPG II performs all operations conditioned by the con¬ 
trol-level indicators in columns 7 and 8 before it performs the operations condi¬ 
tioned by the control-level indicators in columns 9 through 17. 

- If you condition a calculation with a last-record indicator in columns 9 through 17 
when columns 7 and 8 are blank, the calculation is performed only if the last-record 
indicator is set on during detail-time calculations. If the last-record indicator is set 
on when RPG II reaches the end of a file or during total-time calculations, RPG II 
does not perform detail-time calculations. 

In the following example, the record-identifying indicators 01, 02, and 03 must be on to 
perform the calculation SALARY * BONUS1 = GROSS. In the second program line, the 
indicator 04 must be off and indicator 05 must be on to perform the calculation 
SALARY * BONUS2 - GROSS. 


Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

1 

1 

1 

1 

Result 1 
field 1 

1 1 

Decimal positions 

IHalf adjust (H) 

II 

1IResulting 

11 indicators 

11+ - 0 

ll><=+- Comments —+ 

0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # # 

C Oi 02 03SALARY 

C N04 05 SALARY 

MULT B0NUS1 
MULT B0NUS2 

# #- 

GROSS 

GROSS 

-a## # # # 
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2.9.5 Factors 1 and 2 


Use columns 18 through 27 and 33 through 42 to provide the operands for the calculation 
you specify in columns 28 through 32. Use columns 18 through 27 for Factor 1 and columns 
33 through 42 for Factor 2. The operands you use depend on the operation you specify. See 
Part II, Chapter 3 for information on operations and the operands they require. 


Column 

Number 

Allowable 

Values 

Explanation 

18-27 or 
33-42 

Field name 

Names the field that contains data. These are the same 
fields you defined in columns 53 through 58 of the Input 
specification or in columns 43 through 48 of the Calcula¬ 
tion specification. 

18-27 or 
33-42 

Literal 

Specifies an alphanumeric or numeric constant. Numeric 
literals can consist of the digits 0 through 9, one decimal 
point, and one arithmetic sign. Numeric literals cannot 


exceed ten characters and cannot contain blanks. You 
must specify the sign in the leftmost character position. 

Alphanumeric literals can be up to eight characters 
including blanks. You must enclose alphanumeric literals 
in single quotation marks (for example: ’NH’). Use the 
keyboard apostrophe mark for the single quotation mark. 
If you want to use an apostrophe in a literal, you must 
enter two consecutive apostrophes (for example: it’ ’s). 

8-74 Long Specifies an alphanumeric constant that contains 1 to 460 

Character characters. A double quotation mark (“) is placed in the 

Literal first character of the field on the specification. The rest of 

the field is left blank. On the next line, a double quotation 
mark is placed in column 7. Columns 8 through 74 contain 
the character literal, which must be enclosed within single 
quotation marks. The character literal can be anywhere 
on the line. 

If you wish the character literal to continue on the next 
line, follow the ending single quotation mark with a plus 
sign (+), and continue the literal in the same manner on 
the next specification. All the rules for “normal” character 
literals apply to the long character literal placed in col¬ 
umns 8 through 74. 
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Column Allowable Explanation 

Number Values 

If more than one long character literal is entered on a cal¬ 
culation specification, the character literal for the first 
(leftmost) entry is on the next specification, followed by 
the character literal for the second entry, on the specifica¬ 
tion after that. 

Table or Specifies the table name, array name, or array element 

Array you have previously specified in an Extension specifica¬ 

tion. 

Subroutine Specifies one of the following components of a subroutine: 

Name BEGSR (marks the beginning of a subroutine) and EXSR 

(executes a subroutine). 

Special Specifies one of the following special words: UDATE, 

words UMONTH, UDAY, UYEAR, PAGE, PAGE1 through 

PAGE7, *IN, and *INxx. See Part I, Chapter 6 for informa¬ 
tion on special words. See Part I, Chapter 4 for information 
on *IN and *INxx. 

Label Specifies the label for a TAG, GOTO, and ENDSR opera¬ 

tion. See Part II, Chapter 3 for information on TAG, 
GOTO, and ENDSR operation codes. 

Filename Specifies the file name for CHAIN, DSPLY, READ, 

SETLL, or FORCE operations. See Part II, Chapter 3 for 
information on specifying files for these operations. 

Note that you must left-justify the entries in Factors 1 and 2, unless they are numeric 
literals, which must be right-justified. 

In the following example, the literal ’All work and no play make Jack a dull boy.’ is moved 
to the field SHINE. 


0I1I2I3I4I5I6I7I 

SHgM12345678901234567890123456789012345678901234567890123456789012345678901234567890 


** # # # # # #-### # # # 

C MOVE " SHINE 80 

C" 'All work and no play make Jack a dull boy.' 
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This example shows a long character literal continuing on another line. 


0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # # # # # #-### # # # 

C MOVE " SHINE 80 

C" 'All work and no play make Jack '+ 

C" 'a dull boy.' 

ZK-4496-85 


2.9.6 Operation Code 

Use columns 28 through 32 to specify the Operation code that indicates what calculation to 
perform on the operands you specified in columns 18 through 27 and 33 through 42. See 
Part II, Chapter 3 for more information on operation codes. 

Column Allowable Explanation 

Number Values 

28-32 Operation Performs the action specified by the operation code. See 

Code Part II, Chapter 3 for information on operation codes. 

2.9.7 Result Field 

Use columns 43 through 48 to provide the Result field that will contain the outcome of the 
calculation you specified in columns 18 through 42. You can use a field you have previously 
specified in an Input, Calculation, or Extension specification or use columns 49 through 52 
to define its length and decimal positions. 

Column Allowable Explanation 

Number Values 

43-48 Name Identifies the Result field. The Result field can contain a 

field name, table or array name, array element, or one of 
the following special words: PAGE, PAGE 1-7, *IN, or 
*lNxx. 

Rules 

• The Result field name can be any combination of alphanumeric characters; the first 
character must be alphabetic. Embedded blanks are not allowed. 

• You cannot use a look-ahead field, a field defined by an EXTRN operation, UDATE, 
UDAY, UMONTH, or UYEAR as a Result field. 
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2.9.8 Field Length 

If you use the Calculation specification to define a Result field, use columns 49 through 51 
to define the length of the Result field you specified in columns 43 through 48. Otherwise, 
you can leave columns 49 through 51 blank. To prevent undefined or truncated results, 
make sure the length of the Result field is long enough to hold the largest possible result. 

Column Allowable Explanation 

Number Values 

49-51 1-999 Specifies the length of the Result field 

Rules 

• The maximum length for numeric data is 15 digits. 

• The maximum length for alphanumeric data is 999 characters. 

• If the field is described elsewhere in the program and an entry is made in columns 49 
through 51, both entries must specify the same length. 

• Leading zeros can be omitted. 

• Right-justify this entry 

2.9.9 Decimal Positions 

If you use the Calculation specification to define the Result field and the Result field con¬ 
tains numeric data, use column 52 to specify the number of positions to the right of the 
decimal point. 

Column Allowable Explanation 

Number Values 

52 Blank Indicates that this field contains alphanumeric data or 

that the Result field has been defined elsewhere 

0-9 Specifies the number of positions to the right of the 

implied decimal point 

Rules 

• If the field has been previously described in the program, and an entry is made in 
column 52, both entries for Decimal positions must be the same. 

• The number you specify in this column must be smaller than the number in columns 
49 through 51. 

• If the Result field contains alphanumeric data, leave this column blank. 

• When the result is numeric, but has no decimal positions, you must specify zero. 
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2.9.10 Half Adjust 

Use column 53 to specify whether RPG II is to round the numeric data in the Result field. 
RPG II adds 5 to the position immediately to the right of the last digit and puts the new 
value in the Result field. RPG II performs the addition on the absolute value of the number. 
For example, if the result of an arithmetic operation is 123.456 and the Result field speci¬ 
fies two decimal positions, RPG II half-adjusts the value in the Result field to 123.46. 


Column 

Number 

Allowable 

Values 

Explanation 

53 

Blank 

Performs no half-adjusting 


H 

Half-adjusts the numeric data in the Result field 

Rules 




• You cannot half-adjust the Result field of an MVR operation, or of a DIV operation 
immediately followed by an MVR operation. 

• You cannot half-adjust alphanumeric data. 

Additional Information 

• RPG II sets resulting indicators according to the value of the Result field after half¬ 
adjusting. 

• See Table 3-1 in Part II, Chapter 3 for a list of operation codes that allow you to specify 
Half adjust. 

2.9.11 Resulting Indicators 

Use columns 54 through 59 to enter Resulting indicators that test the outcome of a calcula¬ 
tion. You can use these resulting indicators to condition other calculation or output opera¬ 
tions, or to establish field-record relations. 
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Column 

Number 

Allowable 

Values 

Explanation 

54-59 

01-99 

Uses a record-identifying indicator as the resulting indi¬ 
cator. 


H1-H9 

Uses a halt indicator as the resulting indicator. 


K0-K9 

KA-KZ 

Used to condition calculations, output records and output 
fields. They can also be used as resulting indicators. 


L1-L9 

Uses a control-level indicator as the resulting indicator. 


LR 

Uses a last-record indicator as the resulting indicator. 


OA-OG, OV 

Uses an overflow indicator as the resulting indicator. 


U1-U8 

Uses an external indicator as the resulting indicator. 


Rules 

• A resulting indicator is set on if the condition specified is satisfied. If the specified 
condition is not satisfied, the resulting indicator is set off. See Part II, Chapter 3 for 
information on how resulting indicators are used with each operation code. 

• If you use the same indicator to test the results of more than one operation, the last 
operation determines the indicator setting. 

• You cannot use resulting indicators when the Result field contains a nonindexed 
array. 

Additional Information 

• Once a resulting indicator is on, it remains on until one of the following occurs: 

- The operation is repeated and the result resets the indicator 

- The conditions the indicator specifies are not met 

- The indicator is set off by another method (such as the SETOF operation) 

• Using a control-level indicator as a resulting indicator does not automatically set on 
lower-level indicators. 

• Using an external indicator as a resulting indicator allows you to set the indicator, 
then to test the indicator value after the program exits. 
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2.9.12 Comments 

Use columns 60 through 74 for comments. 

Column Allowable Explanation 

Number Values 

60-74 Any Documents the program line 

character 


2.10 Output Specification 

This specification describes the records and fields in an output, update, or input (with the 
ADD option) file. Columns 7 through 37 describe the record and columns 23 through 70 
describe the position and format of each field in the record. 


2.10.1 Output Specification Format 

The format of the Output specification is: 



Type (HDTE) 

IFetch overflow (F) 

Edit codes 

1 X 

/ 

0 

No 

CR 

- 








11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 

1 

N 

Y 

3 

C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

11 End position 






name 

i 

111 1 1 name 

III Format (PB) 
III 1 

III 1+ Constant 






01 

111 1 1 1 

1IBAB A NxxNxxNxxl 

or edit 

word 

+ 

1011121314151617 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

##### # # # 

###—## 





,,,, 
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2.10.2 Specification Type 

Use column 6 to identify the type of specification for every program line. 


Column Allowable 
Number Values 

6 O 


Explanation 


Indicates that this program line is an Output specification 
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2.10.3 File Name 

Use columns 7 through 14 to name the output, update, or input (with the ADD option) file. 

Column Allowable Explanation 

Number Values 

7-14 File name Identifies the name of the output file 

Rules 

• Use the same file name you specified in the File Description specification. An output 
file can be a file you specified as an output file, as an update file, or as an input file with 
A in column 66 of the File Description specification. 

• Left-justify this entry. 

• If columns 7 through 14 are blank, RPG II assumes that the information in this pro¬ 
gram line describes a field or record from the file last named. 

All the records for a single file need not be described together. 

2.10.4 AND and OR Lines 

If you need more than three indicators to condition record output, or if you want to output a 
record under a number of conditions, use columns 14 through 16 to enter AND or columns 


14 through 15 to enter OR. 


Column 

Number 

Allowable 

Values 

Explanation 

14,15 

OR 

Performs the output operation when the conditions for all 
indicators in columns 23 through 31 in either program line 
are met 

14-16 

AND 

Performs the output operation when the conditions for all 
indicators in columns 23 through 31 in both program lines 
are met 

Rules 



• You must use at least one 

indicator per program line in an OR or AND relationship. 

• If you use AND, columns 17 through 22 must be blank. 

• If you 

use AND or OR, columns 7 through 13 must be blank. 


• You can use AND and OR lines only with record description entries, not with field 
description entries. 


You can specify an unlimited number of AND or OR lines. 


2-90 Specifications 



In the following example, if the following conditions are satisfied, RPGII writes the speci¬ 
fied fields and constants: 

• Indicator 01 is off 

• Or, indicator 01 is on 

• And, indicator 23 is off 



Type (HDTE) 

Edit codes 

r 

0 

No 

CR 

- 


IFetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


mi i 

1 

N 

Y 

3 

C 

L 

File 

name 

i 

III 1 Indicators 

III 1 1 Field 

111 1 1 name 

I Blank-after (B) 

II End position 

III Format (PB) 
III 1 

III 1+ Constant 

N 

N 

4 

D 

M 

01 

111 1 1 1 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 

0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 II 

|1234567890i2345678901234567890123456789012345678901234567890i2345678901234567890| 


#* ***** * * * ***—** 


0 

OR 

N0i 


0 

OR 

01 


0 

AND 

N23 


0 


PN 

3 

0 


01 

28 '01 

0 


PNAHE 

10 

0 


(MOUSE 

12 

0 


COLOR 

17 

0 


WEIGHT 

20 

0 


QTY 

24 
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2.10.5 Record Type 

Use column 15 to specify the point in the RPGII program cycle at which a record is output. 
Heading records are normally used to describe the heading information in the output 
report, such as column names, page numbers, and the date. Detail records contain the data 
from input and calculation operations at detail time. Total records usually contain the 
data from the result of calculations on several detail records at total time. Exception 
records are written as a result of using the EXCPT operation in a Calculation specification. 


Column 

Number 

Allowable 

Values 

Explanation 

15 

Blank 

Indicates that this program line describes a field 


H 

Indicates that this program line describes a heading 
record 


D 

Indicates that this program line describes a detail record 


T 

Indicates that this program line describes a total record 


E 

Indicates that this program line describes an exception 
record 


Rules 

• You must specify a Record type for every output record. 

• Records of the same type are tested for output and written in the order in which you 
specify them in the Output specifications. 

There is no difference between a heading record and a detail record. The different entries 
are for documentation purposes only. 

The following example defines heading, detail, total, and exception records. 
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Type (HDTE) 


Edit codes 


, 0 No CR 



IFetch overflow (F) 

1 X 

- 



— 



S1 Space 

1 Y date edit 

Y 

Y 

1 A 

J 



III Skip 

1 Z zero suppress 

Y 

N 

2 B 

K 



III 1 

1 

N 

Y 

3 C 

L 



III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 D 

M 


File 

III 1 1 Field 

II End position 






name 

i 

111 1 1 name 

111 1 1 1 

III Format (PB) 
III 1 

III 1+ Constant 






01 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 


0 1 

112 13 

14 15 


1 

6 

1 

7 ! 

Ii234567890i234567890i234567890i2345678901234567890i2345678901234567890i234567890| 


*# 

00UT44A 

0 


##### * * 
E 

OR 

OR 


0 


N 

3 

0 


PNAME 

10 

0 


UH0USE 

12 

0 


COLOR 

17 

0 


WEIGHT 

20 

0 


QTY 

24 

0 



26 'E' 

0 


N12 16 

28 '16' 

0 


12 01 

28 '12' 

0 


LR 

28 'LR' 

0 

H 



0 


N 

3 

0 


PNAME 

10 

0 


UHOUSE 

12 

0 


COLOR 

17 

0 


WEIGHT 

20 

0 


QTY 

24 

0 



26 'H' 

0 


01 

28 '01' 

0 

D 

17 


0 

OR 

N01 


0 

OR 

01 01 


0 

AND 

N23 


0 


N 

3 

0 


01 

28 '01' 

0 


PNAME 

10 

0 


WHOUSE 

12 

0 


COLOR 

17 

0 


WEIGHT 

20 

0 


QTY 

24 

0 



26 'D' 

0 

T 



0 


N 

3 

0 


PNAME 

10 

0 


WHOUSE 

12 

0 


COLOR 

17 

0 


01 

28 '01' 

0 


WEIGHT 

20 

0 


QTY 

24 

0 



26 'T' 
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2.10.6 ADD and DEL Options 

Use columns 16 through 18 to add and delete records. See Part I, Chapter 5 for information 
on adding and deleting records. 


Column Allowable Explanation 

Number Values 

16-18 ADD Adds a record to an input, output, or update file with an 

indexed, direct, or sequential file organization 

DEL Deletes the last record read in the update file with an 

indexed or direct file organization 


Rules 

• You can add records to input, output, and update files that reside on disk. Therefore, 
the File Description specification must contain DISK in columns 40 through 46 and A 
in column 66. 


• You can delete records only from update files that reside on disk. 

• ADD or DEL must appear on the same line that defines the Record type for the record 
you want to add or delete. 

• If a line in an OR relationship follows an ADD or DEL entry, the ADD or DEL entry 
applies to both lines. 


The following example adds records to the file. 


0 I 1I 2I 3 I 4 I 5 I 6 1 7 M 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


00UT43A DADD 

0 

NIP 

N 

3 

0 


PNAME 

10 

0 


UH0USE 

12 

0 


COLOR 

17 

0 


WEIGHT 

20 

0 


QTY 

24 
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The following example deletes the last record read from the update file. 



Type (HDTE) 

Edit codes 

T 

0 

No 

CR 

- 


1 Fetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


II Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

S'. 


III 1 

1 

N 

Y 

3 

C 

L 

File 

name 

i 

III 1 Indicators 

III 1 1 Field 

111 1 1 name 

I Blank-after (B) 

II End position 

III Format (PB) 
III 1 

III 1+ Constant 

N 

N 

4 

D 

M 

01 

111 1 1 1 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 

1011121314151617 II 

|l23456789012345678901234567890123456789012345678901234567890123456789012345678901 


*# ##### # # # ***—## 


00UT45B EDEL N25 

00UT45C EDEL N25 
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2.10.7 Fetch Overflow 

Use column 16 to specify Fetch overflow. Fetch overflow causes RPG II to check whether 
the overflow indicator assigned to the printer output file is on before printing total, detail, 
or exception records. See Part I, Chapter 6 for information on overflow. 

Column Allowable Explanation 

Number Values 

16 F Executes the overflow routine if overflow has occurred 

Rules 

• An entry in this column is valid only for printer-output files with overflow lines. 

• Do not specify an overflow indicator on the same line as Fetch overflow. 

• If you specify an OR relationship between two lines, you must specify Fetch overflow 
for each record type that requires it in both lines of the OR relationship. 

Additional Information 

• RPG II fetches an overflow routine when overflow occurs and all conditions specified 
by the indicators in columns 23 through 31 are met. 

• When you specify Fetch overflow, only overflow output associated with the file con¬ 
taining the executed fetch is output. 

• The overflow routine does not automatically advance to the next page. 


Specifications 2-95 








The following example specifies Fetch overflow. 


Type (HDTE) Edit codes , 0 No CR - 



1 Fetch overflow (F) 

1 X 

— 


— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


in i 

1 

N 

Y 

3 

C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

II End position 






name 

i 

111 1 1 name 

Mil 1 1 

III Format (PB) 
mi i 






01 

II BAB A NxxNxxNxxl 

ill i 

III 1+ Constant 

or edit 

word 

+ 

10 11 1213141516*17 II 

123456789012345678901234567890123456789012345678901234567890123456789012345678901 

** 

***** * * * 

***—** 





a f m f 


00UT66A EF i Oi 

0 AND 02 03 
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2.10.8 Space Before and Space After 

Use columns 17 and 18 to define the physical format of a printer output file. Use column 17 
to specify the number of lines to advance before printing the next line of output. Use col¬ 
umn 18 to specify the number of lines to advance after printing a line of output. 


Column 

Number 

Allowable 

Values 

Explanation 

17 

Blank 

Does not advance before printing a line of output. 


0-3 

Specifies the number of lines the printer will advance 
before printing a line of output. A value of zero allows 
overprinting. 

18 

Blank 

Does not advance after printing a line of output. 


0-3 

Specifies the number of lines the printer will advance after 
printing a line of output. A value of zero allows overprint- 


ing. 

Rules 

• If you leave columns 17 through 20 blank for a record specification line, RPGII auto¬ 
matically spaces one line after printing the output line. 

• If there are no entries in columns 17 through 20 of an OR line, RPG II uses the entries 
in a preceding line. 

• You cannot define the spacing and skipping for an AND line. 
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Additional Information 


• Because you can space up to only three lines before and after a line of output, you 
cannot specify more than five blank lines between output lines using entries in col¬ 
umns 17 and 18. 

• Spacing to or past the overflow line causes RPGII to set on the overflow indicator. 

2.10.9 Skip Before and Skip After 

Like the Space before and Space after columns, columns 19 through 22 help define the 
physical format of a printer output file. Unlike the entries in columns 17 and 18, the 
entries in columns 19 and 20 can be used to specify more than five lines between lines and 
to specify a move to the next page. 

Use column 19 to specify the line number the printer must move to before printing a line of 
output. Use column 20 to specify the line number the printer must move to after printing a 
line of output. 


Column 

Number 

Allowable 

Values 

Explanation 

19,20 

Blank 

Specifies no skipping before printing a line of output 


01-99 

Causes the printer to move to the line number you specify 
before printing a line of output 


A0-A9 

Causes the printer to move to the line number you specify 
100 (A0) to 109 (A9) before printing a line of output 


B0-B2 

Causes the printer to move to the line number you specify 
110 (B0) to 112 (B2) before printing a line of output 

21,22 

Blank 

Specifies no skipping after printing a line of output 


01-99 

Causes the printer to move to the line number you specify 
after printing a line of output 


A0-A9 

Causes the printer to move to the line number you specify 
100 (A0) to 109 (A9) after printing a line of output 


B0-B2 

Causes the printer to move to the line number you specify 
110 (B0) to 112 (B2) after printing a line of output 


Specifications 2—97 



Rules 

• Follow the same rules in Section 2.8.10 for AND and OR lines. 

• You can specify entries in all Space and Skip columns for a single program line. When 
you do, RPG II executes the entries in the following order: Skip before, Space before, 
print the output line, Skip after, and then Space after. 

• Specifying a Skip entry past the overflow line causes RPG II to set on the overflow 
indicator. See Part I, Chapter 6 for more information. 

• If you specify a Skip entry to the same line number that the printer is currently on, no 
skipping takes place. 

• If you specify a Skip entry to a line number less than the current line number, the 
printer advances to that line number on the next page. 

• The Skip entry cannot exceed the entry for Forms Length (columns 18 and 19 of the 
Line Counter specification). If there is no Line Counter specification, the Skip entry 
cannot exceed the default, line 66. 

2.10.10 Example 

The following example Causes RPG II to 

• Skip to line 27 and space two lines before printing the output line. 

• Skip to line 30 and space three lines after printing the output line. 



Type (HDTE) 


Edit codes 

/ 

0 

No 

CR 

- 


1 Fetch overflow 

(F) 

1 X 

— 

— 

— 

— 

— 


11 Space 


1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 


1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 


1 

N 

Y 

3 

C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

111 1 1 

Field 

II End position 






name 

i 

III 1 1 

111 i i 

name 

i 

III Format (PB) 
mi i 






01 

1IBAB A NxxNxxNxx1 

mi i 

III 1+ Constant 

or edit 

word 

+ 

0 1 

112 1 

3 

1 4 1 E 

j 

1 

6 


1 7 1 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

#* 

***** * * 

* 

*** — ** 





■ ■ i ■ 

0 

D 232730N1P 18 








0 


N 

3 






0 


PNAME 

10 






0 


WH0USE 

12 






0 


COLOR 

17 






0 


WEIGHT 

20 






0 


QTY 

24 
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2.10.11 Indicators 

Use columns 24 and 25,27 and 28, and 30 and 31 to enter previously assigned indicators to 
condition a line of output. 


Column 

Number 

Allowable 

Values 

Explanation 

24-25 

27-28 

30-31 

Blank 

Outputs the record or field. 


Indicator 

Outputs the record or field when the indicator you specify 
is on. 

23,26,29 

N 

Outputs the record or field when the indicator is off. N in 
column 23 conditions the indicator in columns 24 and 25. 
N in column 26 conditions the indicator in columns 27 and 
28. N in column 29 conditions the indicator in columns 30 
and 31. 

Rules 




• When you want an indicator to condition an entire record, enter the indicator on the 
line that specifies the type of record. When you want an indicator to condition a field, 
enter the indicator on the same line as the field name (columns 32 through 37). 

• If you specify more than one indicator on a line, the indicators form an AND 
relationship. 

• You can use overflow indicators in AND or OR lines; however, you can associate only 
one overflow indicator with a group of output indicators. If a line is to be considered an 
overflow line, the overflow indicator must appear on the main specification line or on 
an OR line. 

• If you use an overflow indicator, it must be the same one assigned to the file on the File 
Description specification. 

• You cannot use overflow indicators to condition exception output lines, but you can 
use them to condition fields in an exception record. 
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Additional Information 

• You can use one of the following indicators in columns 24-25, 27-28, and 30-31: 

- Record-identifying (01-99) 

- Control-level (L1-L9) 

- Last-record (LR) 

- Matching-record (MR) 

- Halt (H1-H9) 

- External (U1-U8) 

- Overflow (OA-OG, and OV) 

- K (KA-KZ, and K0-K9) 

- First-page (IP) 

• Keep in mind that RPG II outputs those detail and heading lines conditioned by the 
IP (first-page) indicator, no indicator, or all negative indicators (N in columns 23, 26, 
or 29) before reading the first record from a file. Therefore, use the IP (first-page) indi¬ 
cator to condition only heading and detail output lines that do not depend on data 
from an input record. For a line with no indicators or all negative indicators that 
depends on data from an input record, use a negative first-page indicator (NIP in col¬ 
umns 23 through 31) to prevent the line from being outputted before reading the first 
record. 

• Because the IP (first-page) indicator is set off after the first detail-time output, it can 
be used only to condition heading and detail lines. 

• If you use a control-level indicator with a total record and no overflow indicator, 
RPG II writes the record when a control break occurs and after RPG II processes the 
last record of a control group. 

• If you use a control-level indicator with a detail record and no overflow indicator, 
RPG II writes the record when a control break occurs and after it processes the first 
record of a new control group. 

• If you use a control-level indicator with an overflow indicator, RPG II writes the 
record when a control break occurs and passes the overflow line. 
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The following example causes RPGII to print the specified fields in the detail record if the 
IP (first-page) indicator is off. 



Type (HDTE) 

Edit codes 


0 

No 

CR 

- 


1 Fetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 

1 

N 

Y 

3 

C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

11 End position 






name 

i 

111 1 1 name 

III Format (PB) 
III 1 

III 1+ Constant 






01 

INI 1 1 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 

[011121314151617 II 

1123456789012345678901234567890123456789012345678901234567890123456789012345678901 


## ###*# # # # ###—## 


00UT50A D NIP 

0 N 3 


0 

PNAME 

10 

0 

UH0USE 

12 

0 

COLOR 

17 

0 

UEIGHT 

20 

0 

QTY 

24 

0 

PAGE 

30 


ZK-4504-85 

2.10.12 Field Name 


Use columns 32 through 37 to specify the Field name that identifies the item to be written 


to the output file. 


Column 

Allowable 

Explanation 

Number 

Values 


32-37 

Blank 

Indicates the presence of a constant in columns 45 through 
70. 

Rules 

Name 

Specifies the name of the item to print. The item can be a 
field name, table or array name, array element, or one of 
the following special words (PAGE, PAGE1-7, UDAY, 
UMONTH, UYEAR, UDATE, *IN, *INxx, and *PLACE). 
See Part I, Chapter 6 for information on special words. 


• All field names must have been previously defined in an Input, a Calculation, or an 
Extension specification. 

• Left-justify this entry. 

• You cannot enter a field name if you enter a constant in columns 45 through 70. 
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• If you enter a field name in columns 32 through 37, columns 7 through 22 must be 
blank. 

• If you specify a nonindexed array name, the entire array is output. 

The following example specifies fields in the detail record. 

Type (HDTE) Edit codes , 0 No CR - 

I Fetch overflow (F) I X - 

II Space I Y date edit Y Y 1 A J 

I Skip I Z zero suppress Y N 2 B K 

II I N Y 3 C L 

I I Indicators IBlank-after (B) N N 4 D M 

I I I Field IlEnd position 

I I I name III Format (PB) 

III I III I 

BAB A NxxNxxNxxl III 1+ Constant or edit word + 


0 I i I 2 I 3 I 4 15 I 6 I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## ##*## # # # ### - ## 

00UT50A D NiP 

0 N 3 


0 

PNAME 

10 

0 

WH0USE 

12 

0 

COLOR 

17 

0 

WEIGHT 

20 

0 

QTY 

24 

0 

PAGE 

30 
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2.10.13 EXCPT Name 

When the record type is an exception record (indicated by an E in column 15), a name can 
be placed in columns 32 through 37 of the record line. The EXCPT operation can specify 
the name assigned to a group of records to be written. The name is called an EXCPT name. 

Column Allowable Explanation 

Number Values 

32-37 Blank Identifies exception output records to be written when an 

EXCPT opcode with a blank Factor 2 is executed. 

Name Identifies exception output records to be written when an 

EXCPT opcode with the same name in Factor 2 is exe¬ 
cuted. 


File 

name 

I 

01 
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Rules 

• An EXCPT name must follow the rules for field names. 

• An EXCPT name cannot be the same as a file name, field name, data structure name, 
array name, table name, label, or subroutine name. 

• A group of any number of output records can use the same EXCPT name, and the 
records do not have to be consecutive records. 


2.10.14 Edit Codes 

Use column 38 to specify an Edit code. Edit codes allow you to perform a variety of editing 
functions on the data in a numeric output field. 

Column Allowable Explanation 

Number Values 


38 1 


2 

3 

4 

A 

B 


C 

D 


Prints a number with commas before every third digit to 
the left of the decimal point, prints a zero balance, and sup¬ 
presses signs and leading zeros. 

Prints a number with commas before every third digit to 
the left of the decimal point, suppresses a zero balance, 
suppresses signs, and suppresses leading zeros. 

Prints a number without commas, prints a zero balance, 
and suppresses signs and leading zeros. 

Prints a number without commas, suppresses a zero bal¬ 
ance, suppresses signs, and suppresses leading zeros. 

Prints a number with commas before every third digit to 
the left of the decimal point, prints a zero balance, uses CR 
to represent a negative sign, and suppresses leading zeros. 

Prints a number with commas before every third digit to 
the left of the decimal point, suppresses a zero balance, 
uses CR to represent a negative sign, and suppresses lead¬ 
ing zeros. 

Prints a number without commas, prints a zero balance, 
uses CR to represent a negative sign, and suppresses lead¬ 
ing zeros. 

Prints a number without commas, suppresses a zero bal¬ 
ance, uses CR to represent a negative sign, and suppresses 
leading zeros. 
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Column Allowable Explanation 

Number Values 

J 

K 

L 

M 

X 

Y 

Z 

Rules 

• If you use an Edit code in column 38, columns 45 though 70 must be blank unless you 
specify an Edit code modifier. 

• If you use an Edit code to edit an array, RPG II leaves two spaces to the left between 
the elements of the array. 

• You cannot use Edit codes on numeric data in packed or binary format. 

Additional Information 

• To prevent overlapping of the output fields, leave enough space for the characters that 
the Edit code will insert into the output field. 

• Unedited numeric output fields with negative values are output with the 
overpunched representation of the sign. For example, -1 will be output as J, -2 as K, 
and so on. (See Part II, Chapter 1 for information on overpunched format.) Therefore, 
use an Edit code or Edit word to prevent the output of an overpunched representation 
of a sign. 

Table 2-6 shows the results of several Edit code examples. 


Prints a number with commas before every third digit to 
the left of the decimal point, prints a zero balance, prints a 
negative sign and suppresses leading zeros. 

Prints a number with commas before every third digit to 
the left of the decimal point, suppresses a zero balance, 
prints a negative sign, and suppresses leading zeros. 

Prints a number without commas, prints a zero balance, 
prints a negative sign, and suppresses leading zeros. 

Prints a number without commas, suppresses a zero bal¬ 
ance, prints a negative sign, and suppresses leading zeros. 

Performs no editing. 

Edits a date field using the format month/day/year or the 
format day/month/year, if you specify Inverted print. If the 
first digit of a date field is zero, it is suppressed. 

Suppresses signs and leading zeros. 
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Table 2-6: Edit Codes and Examples 


Edit 

Code 

+12345.67 

+1234567 

-1234.567 

-1234567 

Print Zero 
Balance 

none 

1234567 

1234567 

123456P 

123456P 

yes 

1 

12,345.67 

1,234,567 

1,234.567 

1,234,567 

yes 

2 

12,345.67 

1,234,567 

1,234.567 

1,234,567 

no 

3 

12345.67 

1234567 

1234.567 

1234567 

yes 

4 

12345.67 

1234567 

1234.567 

1234567 

no 

A 

12,345.67 

1,234,567 

1.234.567CR 

1,234,567CR 

yes 

B 

12,345.67 

1,234,567 

1,234.567CR 

1,234,567CR 

no 

C 

12345.67 

1234567 

1234.567CR 

1234567CR 

yes 

D 

12345.67 

1234567 

1234.567CR 

1234567CR 

no 

J 

12,345.67 

1,234,567 

1,234.567- 

1,234,567- 

yes 

K 

12,345.67 

1,234,567 

1,234.567 - 

1,234,567- 

no 

L 

12345.67 

1234567 

1234.567 - 

1234567- 

yes 

M 

12345.67 

1234567 

1234.567 - 

1234567- 

no 


2.10.15 Blank After 

Use column 39 to specify Blank after that causes RPGII to reset the contents of the output 
field after writing it. RPG II resets alphanumeric data with blanks and numeric data with 
zeros. Specifying Blank after is especially useful when accumulating totals for each con¬ 
trol group. 

Column Allowable Explanation 

Number Values 

39 B Causes RPG II to reset the field after writing it 

Rules 

• This column must be blank for look-ahead fields, fields defined by an EXTRN opera¬ 
tion, constants, and the following special words: UDATE, UDAY, UMONTH, 
UYEAR, and *PLACE. 

• If indicators condition the field you want to reset, the same indicators condition Blank 
after. 

• If you specify Blank after for a field that you want to write more than once, enter B in 
this column on the last line specifying output for that field. Otherwise, the field will be 
reset before being output again. 
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The following example specifies Blank after for PAGE3. 



Type (HDTE) 

1 Fetch overflow (F) 

Edit codes 

1 X 

/ 

0 

No 

CR 

- 








11 Space 

1 Y date edit 

Y 

Y 

i 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 

1 

N 

Y 

3 

c 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

II End position 






name 

1 

111 1 1 name 

Mill 1 

III Format (PB) 
III 1 

III 1+ Constant 






01 

11 BAB A NxxNxxNxxl 

or edit 

word 

+ 

0 1 i 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## 

##### # # # 

### —## 





■ • ■ ■ 


00UT50A D NIP 


0 * PAGE3 ZB 50 
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2.10.16 End Position 

Use columns 40 through 43 to indicate the location of an output field or constant. Enter the 
number of the position for the rightmost character. For example, if a field contains 20 char¬ 
acters and you specify 40 as the End position, the output might appear as follows: 

0 ! 1 ; 2 ! 3 ! 4 ! 

12345678901234567890123456789012345678901234567890 

South L y n d e b o r o u 3 h N H 


The numbers above this example are for reference only; they do not appear in the output. 


Column 

Number 

Allowable 

Values 

Explanation 

40-43 

1-9999 

Indicates the position of the rightmost character in an out¬ 
put field or constant 

Rules 




• Right-justify this entry. 

• Leading zeros can be omitted. 

• If fields overlap, the last field you specify on the Output specification is the only field 
that is completely written. 
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• When specifying the End position for an array, use the rightmost position of the last 
element in the array. 

• The End position must be less than or equal to the Record length (columns 24 through 
27 of the File Description specification) of the file to which the record belongs. 

Be sure to allow enough room for the number of characters in each output field and for the 
editing characters you specified using an Edit code or Edit word. 



Type (HDTE) 

Edit codes 


0 

No 

CR 

- 


1 Fetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

i 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 

1 

N 

Y 

3 

C 

L 

File 

name 

i 

III 1 Indicators 

III 1 1 Field 

111 1 1 name 

111 1 1 1 

1 Blank-after (B) 

1lEnd position 

111 Format (PB) 
III 1 

III 1+ Constant 

N 

N 

4 

D 

M 

01 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 

0I1I2I3I4I5I6I7I 

Ii234567890i234567890i234567890i2345678901234567890i234567890i234567890i234567890| 


## ##### # * # ###—## 


0 22 'EMPLOYEE NUMBER' 

0 40 'EMPLOYEE NAME' 

0 57 'REG EARNINGS' 

0 75 'OVER EARNINGS' 
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In the above example, the rightmost character in the 

• First field is in character position 22 

• Second field is in character position 40 

• Third field is in character position 57 

• Fourth field is in character position 75 
The output appears as follows: 

0 ! 1 ! 2 : 3 i 4 ! 5 ! G i 7 

123456789012345078901234567890123456789012345678901234567890123456789012345678 

EMPLOYEE NUMBER EMPLOYEE NAME REG EARNINGS OVER EARNINGS 

The numbers above this example are for reference only; they do not appear in the output. 
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2.10.17 Format 


If an output field contains numeric data, use column 44 to specify its data format. You can 
specify overpunched decimal, packed decimal, or binary. Packed decimal and binary for¬ 
mat conserve disk space. 

Column Allowable Explanation 

Number Values 

44 Blank Indicates that the field contains either alphanumeric 

characters or numeric data and is in overpunched decimal 
format 


P Indicates that numeric data is in packed format 

B Indicates that numeric data is in binary format 


Leave this entry blank for the output field if you specify an Edit code, Edit word, or the 
special word *PLACE. 

The following example specifies packed decimal format for the field QTYP and binary for¬ 
mat for the field QTYB. 


Type (HDTE) Edit codes , 0 No CR - 



1 Fetch overflow (F) 

1 X 


— 

— 

— 



11 Space 

1 Y date edit 

Y Y 

1 

A 

J 



III Skip 

1 Z zero suppress 

Y N 

2 

B 

K 



III 1 

1 

N Y 

3 

C 

L 



III 1 Indicators 

1 Blank-after (B) 

N N 

4 

D 

M 


File 

III 1 1 Field 

IIEnd position 






name 

i 

111 1 1 name 

III Format (PB) 
III 1 

III 1+ Constant 






01 

111 1 1 1 

II BAB A NxxNxxNxx1 

or edit 

word 

+ 


0 1 

123456789012 

112 13 

345678901234567890123456"/ 

14 15 

? 89012345678901234E 

i 1 

)6789012v 

6 

545 

678 

1 

90123 

7 1 
14567890 

** 

***** * * * 

*** — ** 






0 

QTYP 

32P 






0 

QTYB 

38B 
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2.10.18 Constant or Edit Word 

Use columns mentioned below for Edit code modifiers, Constants, and Edit words. This 
section describes the options. 
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2.10.18.1 Edit Code Modifiers 

Use columns 45 through 47 to specify Edit code modifiers. Edit code modifiers can replace 
suppressed zeros to the left of the decimal point with asterisks (asterisk fill) or put a dollar 
sign before the leftmost character (floating currency symbol). To specify these modifiers, 
enter the appropriate value described below. 


Column 

Allowable 

Explanation 

Number 

Values 


45-47 


Replaces suppressed zeros to the left of the decimal point 
with asterisks (*). 

Rules 

’Symbol’ 

Places the currency symbol before the first significant 
digit in a numeric field. The currency symbol is the same 
symbol you define in column 18 of the Control specifica¬ 
tion. 


• Enclose Edit code modifiers in apostrophes. 

• The floating currency symbol will not be printed for a zero balance when you use an 
Edit code that suppresses a zero balance. 

• You cannot use the floating currency symbol or asterisk fill with simple (X, Y, and Z) 
Edit codes. 

• You can specify a currency symbol before an asterisk fill by making the following 
entries: 

- Column 38 (Edit code) - Specify one of the combined Edit codes. 

- Place a currency symbol constant one space before the beginning of the edited field 
on the Output specification. 

- Place an asterisk enclosed in apostrophes (’*’) in columns 45 through 47 on the same 
line as the Edit code. 
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Type (HDTE) 

Edit codes 


0 

No 

CR 

- 


1 Fetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 

1 

N 

Y 

3 

C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

II End position 






name 

i 

111 1 1 name 

111 1 1 1 

III Format (PB) 

III 1 






01 

II BAB A NxxNxxNxxl 

III 1 

III 1+ Constant 

or edit 

word 

+ 

0 1 

112 13 

1 4 1 £ 

) 

1 

i 

> 

1 7 1 

1123456789012345678901234567890123456789012345678901234567890123456789012345678901 

** 

***** * * * 

*** — ** 





■ • ■ • 


0 56 

0 0TEARN1 61 
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In the above example, if the field OTEARN, which is four digits long with two decimal 
positions, contains a zero balance, RPGII prints a dollar sign before the asterisk fill. The 
output might appear as follows: 

0 ! 1 ! 2 ! 3 ! 4 ! 5 ! S ! 7 ! 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

$** ♦ ** 


RPG II uses a dollar sign ($) as the currency symbol unless you specify another symbol in 
column 18 (Currency symbol) of the Control specification. 

2.10.18.2 Constants 

Use columns 45 through 70 to specify Constants. Place a double quotation mark (“) in col¬ 
umn 45 to specify a long character literal as a constant. Constants are used to describe 
constant data in an output file. 


Column 

Number 

Allowable 

Values 

Explanation 

45 

Double 

quotation 

(“) 

Causes RPG II to print the characters within single quota¬ 
tion marks on the line(s) that follow. All the rules for long 
character literals on Calculation specifications apply 
when used on Output specifications. See Factors 1 and 2, 
this chapter, for information on long character literals. 

45-70 

Any 

character 

Causes RPG II to print the characters in columns 45 
through 70. 
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Rules 


• Constants can contain up to 24 characters. 

• You must enclose constants within single quotation marks. Use the keyboard apostro¬ 
phe mark as the single quotation mark (for example, ’Subroutine’). The single quota¬ 
tion marks are not printed. 

• When using constants, leave columns 32 through 39 and column 44 blank. 

• To include an apostrophe in a constant, you must use two consecutive apostrophes to 
represent one apostrophe (for example, ’Subroutine’ ’s calculations’). 

2.10.18.3 Edit Words 

Use columns 45 through 70 to specify Edit words. Edit words can be used to edit a numeric 
field. Edit words consist of three parts: the body, sign status, and expansion. The body is the 
portion of the Edit word that provides space for the digits from the field to be edited. The 
body begins at the leftmost character position of the Edit word and ends at the rightmost 
character position that is to contain a digit from the field to be edited. 

The sign status is the portion of the Edit word that is used to specify whether the field is 
positive or negative and to specify a constant, if needed. The sign status begins at the first 
character position to the right of the body and ends with CR or a negative sign (-). If you 
specify one of these symbols and the field is positive, blank spaces will be substituted in the 
edited field. If you use CR or a negative sign and the field is negative, that symbol will be 
substituted in the edited field. 

If an Edit word contains no CR or a negative sign to the right of the rightmost character 
that is to contain a digit, the Edit word contains no sign status portion. 

The expansion consists of characters that will be printed regardless of the field’s sign sta¬ 
tus. The expansion begins immediately after the sign status (or body, if no sign status is 
used) and continues to the end of the Edit word. 

The following table describes those characters you can use in the body of the Edit word. 
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Column Allowable 
Number Values 

45-70 Blank 
0 


* 


& 


Explanation 


Indicates that the position in the edited field is to contain 
the digit from the same position in the numeric field. 

Indicates that the field is to be zero suppressed. Place the 
zero in the rightmost position where zero suppression is to 
stop. Each leading zero that appears to the left of and 
including the stop position of the numeric field is replaced 
with a blank space in the edited field. The first zero RPGII 
encounters is the zero suppression character. Any zero 
appearing after the first zero is treated like any other 
character. Zero suppression begins at the leftmost position 
in the data and continues up through the stop position 
unless a nonzero digit is encountered to the left of the stop 
position. If RPG II encounters a nonzero digit to the left of 
the stop position, zero suppression stops at the position 
where the nonzero digit is encountered; that digit and all 
following digits to the right of the nonzero digit are 
printed. 

Indicates that the field is to be edited using asterisk pro¬ 
tection. Place the asterisk in the rightmost position where 
asterisk protection is to stop. Each leading zero that 
appears in the data to the left of and including the stop 
position is replaced with an asterisk. The first asterisk 
RPG II encounters is the asterisk protection character. 
Any asterisk appearing after the first asterisk is treated 
like any other character. 

Indicates that the position in the edited field is to be a 
blank space. 
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Column Allowable Explanation 

Number Values 

Symbol Prints the currency symbol. If the currency symbol 

appears in the body of the Edit word immediately to the 
left of the zero suppression, it is printed immediately to 
the left of the first significant digit in the edited field. This 
type of currency symbol is called a floating currency sym¬ 
bol. A floating currency symbol cannot be used with aster¬ 
isk protection. 

The currency symbol in the leftmost position of the Edit 
word indicates that the dollar sign is to be printed in that 
exact position in the edited field. This type of currency 
symbol is called a fixed currency symbol. The following 
example shows both types of currency symbols. 



Type (HDTE) 

Edit codes 

/ 

0 

No 

CR 

- 



1 Fetch overflow (F) 

1 X 

- 

— 

— 

— 

— 



11 Space 

1 Y date edit 

Y 

Y 

i 

A 

J 



III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 



III 1 

1 

N 

Y 

3 

C 

L 



III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 


File 

III 1 1 Field 

1lEnd position 







name 

1 

111 1 1 name 

111 1 1 1 

III Format (PB) 
III 1 

III 1+ Constant 







01 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 


0I1I2I314 -1 51617 1 

|l23456789012345678901234567890123456789012345678901234567890123456789012345678901 


## ##### * # # ###—## 


0 FLOAT 45 '$0 ' 

0 FIXED 45 '$ 
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In the example above, if FLOAT and FIXED contain the characters 1234, the output 
appears as follows: 


0 S 1 ! 2 ! 3 ! 4 ! 5 I 6 ! 7 

1234567890123456789012345678901234567890123456789012345678901234567890123456789 

$1234 
$ 1234 
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Column Allowable Explanation 

Number Values 

Decimal point Indicates the exact position in the edited field where it is to 
or comma be printed. If a decimal point or comma appears to the left 

of the most significant digit, RPG II will replace it with a 
blank space or, if asterisk protection is specified, with an 
asterisk. 

In the following example, RPG II prints a comma before 
the fifth digit from the right and a decimal point before the 
rightmost two digits. 

Type (HDTE) Edit codes , 0 No CR - 

I Fetch overflow (F) I X - 

I I Space I Y date edit Y Y i A J 

11 Skip I Z zero suppress Y N 2 B K 

II I I N Y 3 C L 

II I Indicators IBlank-after (B) N N 4 D M 

III I Field IlEnd position 

III I name III Format (PB) 

II I I I III I 

I BAB A NxxNxxNxxl III 1+ Constant or edit word + 


0 I i I 2I 3 I 4 I 5 I 6 I7 I 
12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## ##### # # 
0 


In the above example, if FLD contains the data 123456, the output appears as follows: 


0 ! 1 ! 2 ! 3 ! 4 ! 5 ! B ! 7 i 

12345678901234567830123450789012345878901234567890123456789012345678901234567830 

$1 ,234*56 


In the above example, if FLD contains the data 56, the output appears as follows: 


0 ! 1 ! 2 ! 3 ! 4 I 5 ! 6 ! 7 ! 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

$ 56 


# ###-## .... 

FLD 45 , . ' 
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01 
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Column Allowable Explanation 

Number Values 

Any other Prints the character(s) in the edited field provided that the 

character position is to the right of the most significant digit in the 

edited field. Any character to the left of the most signifi¬ 
cant digit in the edited field is replaced with a blank space 
or an asterisk if asterisk protection is specified. 



Type (HDTE) 

Edit codes 

r 

0 

No 

CR 

- 



IFetch overflow (F) 

1 X 

— 

— 

— 

— 

— 



11 Space 

1 Y date edit 

Y 

Y 

i 

A 

J 



III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 



III 1 

1 

N 

Y 

3 

C 

L 



III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

h 


File 

III 1 1 Field 

11 End position 







name 

i 

111 1 1 name 

III Format (PB) 
III 1 

III 1+ Constant 







01 

I 1 1 1 1 I 

II BAB A NxxNxxNxxl 

or edit 

word 

+ 


0I1I2I3I4I5I6I7I 

|i2345678901234567890123456789012345678901234567890i23456789012345678901234567890| 


** ***** * * * ***—** 


0 FLD 45 '$ , &BALANCE' 
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In the above example, if FLD contains the data 123456, the output appears as follows: 

0 ! 1 : 2 ! 3 : 4 ! 5 : G ! 7 

12345G789012345G789012345678901234567890123456789012345678901234567890123456789 

$1 »234♦5G BALANCE 

The following table describes those characters you can use in the status portion of the Edit 
word. 

Column Allowable Explanation 

Number Values 

45—70 CR or — Indicates that the specified symbol (CR or a negative sign 

(-)) is to be printed in the edited field if the data is nega¬ 
tive. If the edited field is positive, the specified symbol is 
replaced by blanks. 

Any Prints the specified character(s) in the edited field if the 

character data is negative; otherwise the character is replaced by a 

blank. If an ampersand is specified, it will be replaced by a 
blank space. 
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, 0 No CR 


Type (HDTE) Edit codes 



1 Fetch overflow (F) 

1 X 

— 

— 

— 

— 

— 


11 Space 

1 Y date edit 

Y 

Y 

1 

A 

J 


III Skip 

1 Z zero suppress 

Y 

N 

2 

B 

K 


III 1 

i 

N 

Y 

3 

C 

L 


III 1 Indicators 

1 Blank-after (B) 

N 

N 

4 

D 

M 

File 

III 1 1 Field 

IIEnd position 






name 

■ 

111 1 1 name 

III Format (PB) 
III 1 

III 1+ Constant 






01 

111 1 1 1 

IIBAB A NxxNxxNxxl 

or edit 

word 

+ 

0 1 i 1 2 1 3 1 4 1 5 1 6 1 7 II 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

** 

##### # # # 

###—## 





■ ■■■ 


0 FLD 45 '* , &CR&BALANCE' 
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In the above example, if FLD contains the data -123456, the output appears as follows: 


0 i 1 ! 2 ! 3 ! 4 ! 5 i B ! 7 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

$1>234+56 CR BALANCE 


Rules 

• Leave column 38 (Edit code) blank. 

• You must complete columns 32 through 37 (Field name) and columns 40 through 43 
(End position). 

• Edit words can be used only with overpunched numeric data. (Column 44 (Data for¬ 
mat) must be blank.) 

• Edit words can consist of up to 24 characters. 

• Enclose Edit words in apostrophes. 

• The number of replaceable characters in an Edit word must be greater than or equal 
to the number of digits in the numeric field. 

• If you want all leading zeros to be printed, increase the Edit word by one position to 
the left of the leftmost digit and place a zero in that position. 

• When the floating currency symbol is used, the sum of the number of blanks and the 
zero suppression in the Edit word must be equal to or greater than the number of dig¬ 
its in the edited field. A floating currency symbol is not counted as a digit position. 

• Any zeros or asterisks following the leftmost zero suppression code or asterisk protec¬ 
tion are treated as constants and are not replaced with digits. 
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Chapter 3 

Operation Codes 


Operation codes perform calculations on the operands you specify in Calculation specifica¬ 
tions. The following sections group operation codes by function and discuss each operation 
code in detail. See Table 3-1 at the end of this chapter for a summary of the options you can 
use with each operation code. 


3.1 Arithmetic Operation Codes 

Arithmetic operation codes perform a variety of functions ranging from adding two oper¬ 
ands to taking the square root of an operand. 

When using arithmetic operation codes, consider the following restrictions and default 
characteristics: 

• You can use arithmetic operation codes only with numeric fields and numeric literals. 

• RPG II aligns the operands according to their decimal points before performing any 
arithmetic operation. Also, RPG II aligns the result on the decimal point in the Result 
field which could cause truncation. 

• The contents of Factor 1 and Factor 2 do not change during an arithmetic operation 
unless the same field is used as the Result field. 

• Any existing data in the Result field is replaced with the result of the current 
operation. 

• Make sure the Field length of the Result field is large enough to hold the result of the 
operation. Otherwise, the result of the operation is truncated before being placed in 
the Result field. 

• You can specify Half adjust (column 53 of the Calculation specification) for any arith¬ 
metic operation except for an MVR operation and the DIV operation immediately pre¬ 
ceding it. 

• You can specify the same field for Factor 1 and Factor 2 and/or the Result field, if 
desired. 
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• You can leave Factor 1 blank. If you do, the statement is treated as if the Result field 
were specified in Factor 1. 

• You can specify an entire array as an operand of the ADD, SUB, Z-ADD, Z-SUB, 
MULT, DIV, and SQRT operation codes. See Part I, Chapter 8 for information on using 
arrays in calculations. 

• No field in an arithmetic operation can be longer than 15 digits. 

• RPGII performs all arithmetic operations algebraically. 

• The result of all arithmetic operations is signed. The sign of the result of an arithme¬ 
tic operation depends on the operation. 

Addition: 

- If Factor 1 and Factor 2 have like signs, the Result field has the same sign. 

- If Factor 1 and Factor 2 have unlike signs, the Result field uses the sign of the factor 
with the largest absolute value. 

Subtraction: 

- Change the sign of Factor 2 (positive to negative or negative to positive) and use the 
same rules as for addition. 

Multiplication: 

- If Factor 1 and Factor 2 have like signs, the sign of the Result field is positive. 

- If Factor 1 and Factor 2 have unlike signs, the sign of the Result field is negative. 
Division: 

- If Factor 1 and Factor 2 have like signs, the sign of the Result field is positive. 

— If Factor 1 and Factor 2 have unlike signs, the sign of the Result field is negative. 

- The sign of the remainder is the same as the sign of Factor 1. 

3.1.1 ADD 

ADD adds the contents of Factor 1 to Factor 2 and puts the sum in the Result field. If 
you leave Factor 1 blank, the statement is treated as if the Result field were specified in 
Factor 1. 

3.1.2 Z-ADD 

Z-ADD assigns the value of Factor 2 to the Result field. 
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3.1.3 SUB 


SUB subtracts the contents of Factor 2 from the contents of Factor 1 and puts the differ¬ 
ence in the Result field. If you leave Factor 1 blank, the statement is treated as if the Result 
field were specified in Factor 1. 

3.1.4 Z-SUB 

Z-SUB multiplies the contents of Factor 2 by -1 and puts the result in the Result field. 

3.1.5 MULT 

MULT multiplies Factor 1 by Factor 2 and puts the product in the Result field. If you leave 
Factor 1 blank, the statement is treated as if the Result field were specified in Factor 1. 

The Field length of the Result field for a MULT operation should equal the sum of the Field 
lengths of Factor 1 and Factor 2. This procedure makes sure the Result field can contain 
the maximum value. 

3.1.6 DIV 

DIV divides Factor 1 by Factor 2 and puts the quotient in the Result field. If you leave 
Factor 1 blank, the statement is treated as if the Result field were specified in Factor 1. 

Factor 2 cannot be zero. If it is, a run-time error occurs. The remainder is lost unless you 
use the MVR operation immediately following the DIV operation. 

3.1.7 MVR 

MVR moves the remainder from the division operation on the preceding line to the Result 
field. The Decimal position of the remainder is the greater of either of the following: 

1. The number of Decimal positions specified for Factor 1 

2. The sum of the number of Decimal positions specified for Factor 2 and the Result 
field of the preceding DIV operation 

The sign of the remainder is the same as the sign of Factor 1 in the DIV operation. 

Because DIV and MVR operation codes work together, use the same indicators to condition 
both operations. 

You cannot specify Half adjust (column 53 of the Calculation specification) for a DIV opera¬ 
tion immediately followed by an MVR operation. 

You cannot use the MVR operation if in the immediately preceding DIV operation you 
specified an entire array (nonindexed) in the Result field. 
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3.1.8 SQRT 

SQRT calculates the square root of Factor 2, half adjusts the value, and puts the result into 
the Result field. The result of a SQRT operation is always half adjusted. Factor 2 cannot be 
a negative number. If the field contains a negative number, a run-time error occurs. If you 
use a negative numeric literal, a compile-time error occurs. 

3.1.9 XFOOT 

XFOOT puts the sum of all the array elements into the Result field. Factor 2 contains the 
name of the array. If the Result field contains an array element of the array you specify in 
Factor 2, the original value of the element is used during the operation. 

You can half adjust the contents of the Result field. 


3.1.10 Example 

The following example demonstrates the use of arithmetic operation codes: 




Field length 

Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

I Half adjust (H) 

II 

1 1 

1 

11 Resulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

10 1-112 

1 3 1 

4 1 

5 16 1 


123456789012345678901234567890123456789Q123456789Q123456789012345678901234567890| 


** * 

* 

K * 

# #- 

—### # # # 

12 C 

PURCH 

SUB DWNPAY 

AMTFIN 

62H 

13 C 

AMTFIN 

MULT .18 

FINCHG 

62H 

14 C 

FINCHG 

ADD AMTFIN 

AMTDUE 

62H 

15 C 

AMTDUE 

DIV 13 

MTHPAY 

52 

16 C 


MVR 

REMAIN 

42 

17 C 


Z-ADD5.00 

TOTDUE 

62 

18 C 


ADD AMTDUE 

TOTDUE 



30 

c 

Z-SUB10.00 

EARPAY 

42H 

31 

c 

• 

Z-ADD6.99 

LATCHG 

32H 

46 

c 

SQRT FINCHG 

TAX 

42H 
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For the example above, the following table lists the data in each operand before and after 
the operation. 
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Program 

line 

Factor 1 

Operation 

Factor 2 

Result 

Field 

12 

122.99 

- 

100.00 

22.99 

13 

1200.00 

* 

.18 

216.00 

14 

216.00 

+ 

1200.00 

1416.00 

15 

1416.00 

/ 

13 

108.92 

16 


MVR 


0.04 

18 


ADD 

1416.00 

1421.00 

30 


Z-SUB 

10.00 

-10.00 

31 


Z-ADD 

6.99 

6.99 

46 


SQRT 

216.00 

14.70 


3.2 Move Operation Codes 

Move operation codes transfer data from a field in Factor 2 to the Result field. Although the 
contents of Factor 2 remain unchanged, you can move all or part of the field in Factor 2, 
and either retain or change the format of the data as you move it. 

In move operations, RPGII ignores the Decimal positions of numeric fields. You cannot use 
resulting indicators with any move operation. 

3.2.1 MOVE 

MOVE transfers the contents of Factor 2 to the Result field. The transfer begins with the 
rightmost character of Factor 2 to the rightmost character of the Result field. If the Result 
field is not large enough to accommodate Factor 2, RPG II moves only enough characters 
(beginning with the rightmost character) to fill the Result field. If the Field length of the 
Result field is longer than Factor 2, the leftmost characters of the Result field are not 
changed. If RPG II transfers numeric data, the sign of the Result field is the same as the 
sign of Factor 2. 

When you move an alphanumeric field to a numeric field, RPG II converts the digit portion 
of each character to its corresponding numeric character and then moves the numeric 
character to the Result field. RPG II converts the zone portion of the rightmost character to 
its corresponding sign and then moves the sign to the rightmost character position of the 
numeric Result field, where it becomes the sign of that field. 
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3.2.2 MOVEA 


MOVEA transfers data from Factor 2 to the Result field. Either Factor 2 or the Result field 
must contain an array or array element. If you specify an array element, it specifies the 
beginning position of the transfer. Both Factor 2 and the Result field must be character 
fields or arrays. 

You can move several contiguous array elements to a single field or move a single field to 
several contiguous array elements. 

Movement of data from Factor 2 to the Result field begins with one of the following: 

• The leftmost character of the first element in the array, if you specify an entire array 
(nonindexed) 

• The leftmost character of the element you specify, if you specify an array element 
(indexed) 

• The leftmost character of the field, if you specify a field 

The length of Factor 2 and the Result field is determined by the length of one of the follow¬ 
ing: 

• Entire array, if you specify an entire array (nonindexed) 

• Array from the specified array element to the end of the array, if you specify an array 
element (indexed) 

• Field, if you specify a field 

If the Field length of Factor 2 is greater than the Field length of the Result field, RPG II 
does not move the excess rightmost characters. If the Field length of the Result field is 
greater than the Field length of Factor 2, the rightmost characters in the Result field 
remain unchanged. 

Array element boundaries are ignored in a MOVEA operation. Therefore, movement of 
data into the Result field can end in the middle of an array element. 

3.2.3 MOVEL 

MOVEL transfers the contents of Factor 2 to the Result field. The transfer begins with the 
leftmost character of Factor 2 to the leftmost character of the Result field. 

When the Field length of Factor 2 is equal to the Field length of the Result field, the follow¬ 
ing rules apply: 

• If Factor 2 contains alphanumeric data and the Result field is alphanumeric, RPG II 
moves characters without changing them. 

• If Factor 2 contains numeric data and the Result field is numeric, the sign of Factor 2 
becomes the sign of the Result field. 
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• If Factor 2 contains numeric data and the Result field is alphanumeric, RPGII moves 
the sign with the rightmost character position. 

• If Factor 2 contains alphanumeric data and the Result field is numeric, each character 
is converted to its corresponding numeric digit and moved to the Result field. The zone 
portion of the rightmost character in Factor 2 is used to determine the sign of the 
Result field. 

When the Field length of Factor 2 is longer than the Field length of the Result field, the 
following rules apply: 

• If Factor 2 contains alphanumeric data and the Result field is alphanumeric, RPG II 
moves only the number of characters needed to fill the Result field. 

• If Factor 2 contains numeric data and the Result field is numeric, the sign of Factor 2 
becomes the sign of the Result field. 

• If Factor 2 contains numeric data and the Result field is alphanumeric, the Result 
field contains only numeric data; that is, the sign of Factor 2 is not used. 

• If Factor 2 contains alphanumeric data and the Result field is numeric, the leftmost 
character(s) of Factor 2 are converted to the corresponding numeric digit(s) and 
moved to the Result field. The zone portion of the rightmost character in Factor 2 is 
used to determine the sign of the Result field. 

When the Field length of Factor 2 is shorter than the Field length of the Result field, the 
following rules apply: 

• If Factor 2 contains either numeric data or alphanumeric data and the Result field is 
numeric, RPG II moves the digits of numeric fields or the corresponding numeric dig¬ 
its, if alphanumeric, of Factor 2 into the leftmost character positions of the Result 
field. The sign of the Result field remains unchanged. 

• If Factor 2 contains either numeric or alphanumeric data and the Result field is 
alphanumeric, RPG II moves the data into the Result field beginning with the 
leftmost character position. The rightmost character positions in the Result field 
remain unchanged. 

3.2.4 Example 

In the following example, the pre-execution-time array ARR1 is read from the input file 
ARRFILE and is copied to the execution-time array DUPARR. The array is modified by 
moving the input field INPFLD to the second and third elements of the array. Additionally, 
the field MYREC consists of the first element in ARR1 and the last three characters of the 
third element in ARR1. 
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! 0 I 1 I 2 i 3 I 4I 5 I 6I 7 I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


E ARRFILE 
E 

IARRFILE AA 01 

I 

C 

C 

C 

C 


ARRi 6 6 

DUPARR 6 


MOVEAARRi 
MOVEAINPFLD 
MOVE ARRi,3 
MOVELARRi,! 


5 

5 

i 10 INPFLD 
DUPARR 
ARRi,2 
MYREC 8 
MYREC 
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For this example, the input file (ARRI) contains the following data: 


Field 

Data 

ARR1,1 

12345 

ARRI,2 

67890 

ARRI,3 

zzzzz 

ARRI,4 

zzzzz 

ARRI,5 

zzzzz 

ARRI,6 

zzzzz 

INPFLD 

ABCDEFGHIJ 


After executing the program, the fields would contain the following data: 


MYREC 

- 12345HIJ 

ARR1,1 

= 12345 

ARRI,2 

=ABODE 

ARRI,3 

= FGHIJ 

ARRI,4 

= zzzzz 

ARRI,5 

= zzzzz 

ARRI,6 

= zzzzz 

DUPARR 

= 1234567890ZZZZZZZZZZZZZZZZZZZZ 
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3.3 Set Operation Codes 

Set operation codes (SETON and SETOF) set indicators on and off. They affect only those 
indicators in columns 54 through 59. 

If you use set operation codes to set control-level indicators on and off, they do not affect 
lower control-level indicators. 

3.3.1 SETON 

SETON sets on the indicators you specify in columns 54 and 55, 56 and 57, and 58 and 59. 
You cannot set the first-page (IP) or matching-record (MR) indicators on. 

If you use SETON to set the LR indicator on at total time, processing stops after RPG II 
finishes total-time output operations. 

If you use SETON to set the LR indicator on at detail time, processing stops after RPG II 
finishes the next total-time output operation. 

If you use SETON to set halt indicators on and they are not set off before RPG II finishes 
detail-time output operations, processing stops. 

3.3.2 SETOF 

SETOF sets off the indicators you specify in columns 54 and 55, 56 and 57, and 58 and 59. 
You cannot set the first page (IP) or matching-record (MR) indicators off. 

In the following example 

• The SETON operation sets indicators 11 and 22 on. 

• The SETOF operation sets indicator 33 off. 


Field length 


Control level 

1 

1 Indicators 

1 1 

1 1 Factor 

1 1 1 

Cl NxxNxxNxxl 

Operation 

1 

1 Factor 

1 2 

1 1 

1 

1 

1 

1 

Result 1 
field 1 

1 1 

Decimal positions 

I Half adjust (H) 

II 

1IResulting 

11 indicators 

11+ - 0 

I|> < = +- Comments —+ 

1011121314151617 11 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 

## # * 

# # 

* #- 

-### # # # 

c 

SETON 


1122 

c 

SETOF 


33 
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3.4 Subroutine Operation Codes 

Subroutine operation codes are used to identify and execute subroutines. A subroutine is a 
group of Calculation specifications that you can execute more than once in a single pro¬ 
gram cycle. 

You can use SR in columns 7 and 8 to indicate that the specification is part of a subroutine, 
although this is optional. You cannot use control-level indicators in columns 7 and 8 of a 
subroutine. However, you can use any indicator in columns 9 through 17. Also, you can use 
AN and OR in columns 7 and 8 to set up a relationship between two program lines. 

You can use up to 254 subroutines in a program. Subroutines must be placed after all other 
calculations. Subroutines cannot be nested or recursive. However, you can use EXSR to 
call one subroutine from another. 

3.4.1 BEGSR 

BEGSR indicates the beginning of a subroutine and must be the first specification in a 
subroutine. Factor 1 contains the name of the subroutine. All other columns in the same 
specification must be left blank except for an optional SR in columns 7 and 8. 

3.4.2 ENDSR 

ENDSR indicates the end of a subroutine and must be the last specification in a subrou¬ 
tine. Factor 1 can contain a label for a GOTO operation within the subroutine. All other 
columns in this specification must be blank, except for an optional SR in columns 7 and 8. 

Once the program reaches the ENDSR operation, it returns program control to the specifi¬ 
cation immediately following the EXSR operation code that invoked the subroutine. 

3.4.3 EXSR 

EXSR executes a subroutine. Factor 2 contains the name of the subroutine. It must be the 
same name you used in Factor 1 of the BEGSR operation. You can use control-level and 
conditioning indicators to condition EXSR. 

After the program performs the operations in the subroutine, control branches to the speci¬ 
fication immediately following EXSR. 

3.4.4 Example 

In the following example, line 11 causes RPGII to execute the subroutine SUB1. The sub¬ 
routine consists of lines 22 through 24. 
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Field length 


Control level 

1 

1 Indicators 

Operation 

1 

1 

1 

1 

Decimal positions 

IHalf adjust (H) 

11 

1 1 

1 

1IResulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

Cl NxxNxxNxxl 

1 1 

1 1 

11> < = +- Comments —+ 

1011121314151617 11 

|l23456789012345678901234567890123456789012345678901234567890123456789012345678901 


## # 

# 

* # 

# # — ### 

ii C 02 


EXSR SUBi 


22 CSr’ 

SUBi 

BEGSR 


23 CSR 02 

HOURS 

MULT RATE 

DAYPAY 52H 

24 CSR 


ENDSR 
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3.5 Bit Operation Codes 

Bit operation codes set and test bits. You must use one-character alphanumeric fields in 
Factor 2 and the Result field. 

3.5.1 BITON 

BITON sets on the bits you specify in Factor 2 in the Result field, replacing the value in the 
Result field. Factor 2 contains the source of bits in bit numbers or a field name. 

You can set on bit numbers 0 through 7. Zero is the leftmost bit. You must enclose the bit 
number in apostrophes. For example, to set bits 1, 2, and 3 on, enter ‘123’ in Factor 2. You 
cannot specify a bit number more than once. 

The field name is a one-character alphanumeric field, table, or array element. The bits that 
are on in the field name are set on in the Result field. If you specify an array element, each 
array element must be a one-character field. 

You can use indicators in columns 7 through 17, but the following columns must be left 
blank: 

• Columns 18 through 27 (Factor 1) 

• Column 52 (Decimal positions) 

• Column 53 (Half adjust) 

• Columns 54 through 59 (Resulting indicators) 
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3.5.2 BITOF 


BITOF sets off the bits you specify in Factor 2 in the Result field, replacing the value in the 
Result field. To specify operands for BITOF, follow the same guidelines as for BITON. 

3.5.3 TESTB 

TESTB compares the bits in Factor 2 with the corresponding bits in the Result field. Factor 
2 can contain bit numbers or a one-character alphanumeric field. Bit numbers and one- 
character alphanumeric fields follow the same rules as those for BITON and BITOF. 

Indicators in columns 54 through 59 reflect the status of the bits in the Result field; there¬ 
fore, you must assign at least one resulting indicator. You can set up to three resulting 
indicators but no more than two resulting indicators can be identical. 

If Factor 2 is a field in which all bits are off, no resulting indicator is set on; otherwise, 
indicators in columns 54 through 59 indicate the result of the comparison as follows: 

• RPGII sets the indicator in columns 54 and 55 on, if all bits specified in Factor 2 are off 
in the Result field. 

• RPG II sets the indicator in columns 56 and 57 on, if some bits specified in Factor 2 are 
on in the Result field and some are off. 

• RPG II sets the indicator in columns 58 and 59 on, if all bits specified in Factor 2 are on 
in the Result field. 

You can use indicators in columns 7 through 17, but the following columns must be left 
blank: 

• Columns 18 through 27 (Factor 1) 

• Column 52 (Decimal positions) 

• Column 53 (Half adjust) 

3.5.4 Example 

In the following example 

• Line 34 sets the bits 1,2, and 3 on in the Result field FLD1. 

• Line 35 tests the bits 1, 2, and 3 in the Result field FLD1. If all the bits are on, indica¬ 
tor 11 is set on. If one or more of the bits are off, indicator 11 is set off. 

• Line 36 sets the bits 4, 5, and 6 off in the Result field FLD2. 

• Line 37 tests the bits 4, 5, and 6 in the Result field FLD2. If all the bits are off, indica¬ 
tor 22 is set on. If one or more of the bits are on, indicator 22 is set off. 
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3.6 Compare Operation Code 

COMP tests fields for certain conditions. Based on the result of the comparison, you can 
assign resulting indicators to condition calculation and output operations. 

COMP compares the contents of Factor 1 to the contents of Factor 2. An indicator in col¬ 
umns 54 through 59 indicates the result of the comparison as follows: 

• If Factor 1 is greater than Factor 2, RPGII sets the indicator in columns 54 and 55 on. 

• If Factor 1 is less than Factor 2, RPG II sets the indicator in columns 56 and 57 on. 

• If Factor 1 is equal to Factor 2, RPG II sets the indicator in columns 58 and 59 on. 

You must specify at least one resulting indicator. The Result field must be left blank. 

When using the COMP operation code, consider the following restrictions and default 
characteristics: 

• If you compare numeric fields, the fields are aligned at their implied decimal point. 
Fields are filled with zeros to the left and right of the decimal point until both fields 
are equal in length. For example, if you compare 1234.56 to 1.2, RPG II fills the second 
field (1.2) with zeros (0001.20) until both fields are equal in length. 

• If you compare alphanumeric fields of unequal lengths, the fields are aligned at the 
leftmost character. Shorter fields are filled with blanks until the two fields are equal 
in length. 

• RPG II compares numeric fields algebraically. 

• Positive numeric fields are greater than negative numeric fields. 
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• If you have specified an alternate collating sequence, RPG II translates character 
fields to the alternate collating sequence before comparing them. 

• You cannot compare an alphanumeric field to a numeric field. 

• You cannot compare entire arrays (nonindexed). 

In the following example, if the contents of the field CODE are greater than 1, RPG II sets 
indicator 11 on and sets indicators 22 and 33 off. If the contents of CODE are less than 1, 
RPG II sets indicator 22 on and sets indicators 11 and 33 off. If CODE is equal to 1, RPG II 
sets indicator 33 on and sets indicators 11 and 22 off. 
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3.7 Input and Output Operation Codes 

You can use the following operation codes to alter the normal input and output sequence, 
enabling the program to read and write records during calculations. 

3.7.1 CHAIN 

CHAIN reads a record from a file during calculations and places the contents of the record 
into the fields you specify on the Input specification. You can read records randomly from a 
sequential, a direct, or an indexed file. 

If you want to read a record from a sequential or a direct file, Factor 1 must contain the 
relative record number of that record. If you want to read a record from an indexed file, 
Factor 1 must contain a field name or a literal that is the key of that record. The Field 
length of the field or literal specified in Factor 1 must be the same as the Field length of the 
key. 

Factor 2 contains the name of the file from which the record is read. This file must be the 
same file you describe in the File Description specification with a C or an F in column 16 
(Type). 
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You can use any indicator in columns 7 through 17, but columns 43 through 53, and 56 and 
57 must be left blank. If you condition the chained or full-procedural file with an external 
indicator, use the same indicator to condition the CHAIN operation. 

You can specify an indicator in columns 54 and 55 to verify the CHAIN operation. If RPGII 
cannot locate the record, it sets the indicator in these columns on. If you do not use an 
indicator in columns 54 and 55, and RPG II cannot locate the record, a run-time error 
occurs. If RPG II cannot locate the record, you can add a record to the chained file (if you 
use a resulting indicator to indicate that a record has not been found), but you cannot 
attempt to update the record. 

You can specify on a CHAIN operation that if a record is locked, to set on an indicator. 
Enter the indicator for a locked record in columns 58 and 59 of a Calculation specification. 
If you specify an indicator in columns 58 and 59, the program will not wait for the record to 
become unlocked before proceeding, and will turn on the indicator to show that the 
requested record was locked. If you do not specify the indicator, the program will wait until 
any record lock is released before proceding. This indicator is only allowed on CHAINs to 
files that are marked as SHARE (S or R in column 68 on File specifications). The file cannot 
be an output file. Note that if another program has locked a record for update, but uses the 
file sharing option R, then a CHAIN operation that accesses that record will be successful; 
no lock will be seen and an indicator in columns 58 and 59 will be turned off. 

If you chain to a file with packed keys, the field in Factor 1 of the CHAIN operation must be 
numeric and have the same number of digits as the key in the chained or full-procedural 
file. Packed key fields can be up to 8 bytes long. 

If you use one or more chained or full-procedural files during the same program cycle, and 
the previous CHAIN operation was successful, then any record-identifying indicators you 
use remain on throughout the cycle. If you use a chained file more than once during the 
same program cycle, only the last record processed can be updated during output, unless 
you specify exception output for each CHAIN operation. 

The CHAIN operation is also used to load a direct file (a chained output file). Use the 
CHAIN operation to position the file to the record you want to add to the file. 

See Part I, Chapter 5 for information on processing files. 

In the following example 

• Line 33 retrieves the record from the input file FILE1 with the relative record number 
specified in the field RECNO. If the record is not found, RPG II sets indicator 11 on. If 
the record is found, RPG II sets indicator 11 off. 

• Line 34 branches to a TAG operation to terminate the program if the previous CHAIN 
operation causes a record-not-found error. 

• Line 55 retrieves the record with the key 761 from the indexed file FILE2. If a record 
with a key of 761 does not exist, RPG II sets indicator 22 on. If a record with a key of 
761 does exist, RPG II sets indicator 22 off. 


Operation Codes 3-15 



0I1I2I3I4I5I6I7I 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 



FFILE1 

IC F 

80 DISK 



FFILE2 

IC F 

80 5AI 10 DISK 


33 

■ 

C 

RECN0 

CHAINFILE1 

ii 

34 

C ii 


GOTO END 


55 

■ 

c 

761 

CHAINFILE2 

22 


ZK-4520-85 

3.7.2 DSPLY 

DSPLY allows you to display, on line, up to 511 characters at run time. RPGII can 

• Display up to 511 characters from a field without suspending program execution. Fac¬ 
tor 1 names the field to display. 

• Display the number of characters up to one less than your screen width from the 
Result field. The program suspends execution after displaying the Result field. The 
cursor is positioned at the next line where you can enter a new value for the Result 
field from the terminal. 

When entering a new value for the Result field, terminate the input by pressing either a 

RETURN key or a TAB key. If you press only a RETURN key or a TAB key for the new 

value of the Result field, the data in the Result field remains the same. 

When using DSPLY, observe the following restrictions and default characteristics: 

• You cannot change the contents of a literal; therefore, do not specify a literal in the 
Result field. 

• The maximum length of the Result field is one character less than the screen width. 

When entering data for the Result field, consider the following characteristics: 

• You do not need to fill numeric data with leading zeros. 

• Numeric data is aligned on the decimal point when entered into the Result field. 

• Alphanumeric data is left-justified when entered into the Result field. 

• If you enter no characters and press either the RETURN key or the TAB key, the value 
in the Result field remains unchanged. 
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3.7.3 Example 

In the following example, if the data in NUMBER is greater than 100.0, the number will 
be displayed on the terminal followed on the next line by the current value of RESNO. 
Then, you can enter a new value for RESNO followed by pressing the RETURN key. 
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3.7.4 EXCPT 

EXCPT allows you to write a variable number of records during detail-time or total-time 
calculations. To do this you must specify the following entries: 

• On the Calculation specification: 

- EXCPT as the operation code 

- blanks or an EXCPT name in Factor 2 

• On the Output specification: 

- E in column 15 (Type) for the record you want to write 

- blanks or an EXCPT name in columns 32 through 37 (Field name) 

The EXCPT operation writes those records that have an E in column 15 of the Output 
specification and that satisfy the conditions specified by the conditioning indicators. In 
addition, if the EXCPT operation has a blank Factor 2, only exception records with blanks 
in columns 32 through 37 of the O specification will be written; if the EXCPT operation has 
an EXCPT name in Factor 2, only exception records with the same name in columns 32 
through 37 of the O specification will be written. 

You can use indicators in columns 7 through 17 of the Calculation specification. Factor 2 
can contain blanks or an EXCPT name. All other columns must be blank. 

An EXCPT name can be used on multiple EXCPT output record lines. Only exception 
records, not heading, detail, or total records, can contain an EXCPT name. 

In the following example, line 22 tells RPGII to write the record described in line 89 dur¬ 
ing calculations if indicators 01, 02, and 03 are on. Line 34 tells RPG II to write the record 
described in line 95 if indicator 04 is on. 
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3.7.5 FORCE 

FORCE allows you to select the next file from which a record is read when doing multifile 
processing. You can select primary or secondary input and update files. Factor 2 contains 
the name of the file. 

You can use conditioning indicators, but all other columns must be left blank. 

When RPG II executes a FORCE operation, it reads, at the next program cycle, a record 
from the file you specify. If you specify more than one FORCE operation during the same 
program cycle, RPG II ignores all FORCE operations except the last. 

Although FORCE operations override normal multifile processing, they cannot override 
the first record selected by the program. Reading the first record occurs in the first cycle 
before the first pass through calculations. 

If a FORCE operation is issued for a file that is at its end-of-file, the file is not selected for 
processing. In this case, normal multifile processing logic selects the next record. 

In the following example, RPG II reads the next record from the file SPECFIL at the next 
program cycle if indicators 01, 02, and 03 are on. 
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3-18 


Operation Codes 







3.7.6 READ 


READ causes RPGII to read a record from a demand or full-procedural file. Factor 2 con¬ 
tains the name of the file from which a record is read. You can read a record from the follow¬ 
ing types of input and update files: 

• Sequential and direct disk files processed consecutively 

• Indexed disk files processed sequentially by key or by limits 

You can use any indicators in columns 7 through 17 and in columns 58 and 59. RPG II sets 
the indicator in columns 58 and 59 on when an end-of-file condition occurs, or for each 
READ operation following an end-of-file condition. If there is no indicator in columns 58 
and 59, a run-time error occurs. Columns 18 through 27 and 43 through 57 must be left 
blank. 

If RPG II does not open a file because an external indicator is off, a READ operation on the 
file causes an end-of-file condition to occur. 

In the following example, RPG II reads the next record from the file SPECFIL if indicator 
99 is off. If an end-of-file condition occurs, RPG II sets indicator 99 on. If an end-of-file con¬ 
dition does not occur, RPG II sets indicator 99 off. 
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3.7.7 SETLL 

SETLL positions a file at the next record with a key that is greater than or equal to the key 
you specify in Factor 1. Factor 2 contains the name of the file for which the lower limit is 
set. Factor 2 must be an indexed demand or full-procedural file being processed sequen¬ 
tially within limits. 

Factor 1 can be a field name or a literal, and must be the same size as the key specified in 
the File Description specification. If the keys in the file are in packed decimal format, Fac¬ 
tor 1 must be numeric. 

You cannot use a record address file and the SETLL operation on the same file. 
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If the program issues a READ operation before issuing a SETLL operation, processing 
begins with the first record in the file. 

When RPGII reaches the end of a file, you can use another SETLL operation to reposition 
the file. If the SETLL operation is not successful, you must reposition the file with a suc¬ 
cessful SETLL operation. 

When a SETLL operation is performed on a record whose key is greater than the highest 
key in the file, the subsequent READ operation will be as if the current record pointer had 
not changed from the previous READ operation. If a successful SETLL operation is done 
followed by a SETLL operation for a record whose key is greater than the highest key in 
the file, with no intervening READ operation, the next READ operation will be as if the 
current record pointer had not changed from the previous READ operation. In the latter 
case, it appears as if the successful SETLL operation never occurred, because it was fol¬ 
lowed by a failing SETLL operation. 

In the following example, KEY 1 contains the lower key limit for the file FILE1. The READ 
operation retrieves the first record with a key that is greater than or equal to the field 
KEY1. 
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3.8 Branching Operation Codes 

RPG II performs operations in the order they appear in your program. However, you can 
use branching operation codes to skip or repeat operations under certain conditions. 


3.8.1 GOTO 

GOTO transfers program control to the label you specify in Factor 2. 
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GOTO is especially useful in the following situations: 

• Skipping calculations when certain conditions occur 

• Performing certain calculations for certain record types 

• Repeating calculations 

You can transfer control in the following cases: 

• To a previous line 

• From one detail-time calculation line to another 

• From one total-time calculation line to another 

• From one subroutine calculation to another inside the same subroutine 
You cannot transfer control from the following lines: 

• Detail-time calculation line to a total-time calculation line 

• Total-time calculation line to a detail-time calculation line 

• Line inside a subroutine to a line outside that subroutine 

• Line outside a subroutine to a line inside a subroutine 
When using GOTO, the following columns must be left blank: 

• Columns 18 through 27 (Factor 1) 

• Columns 43 through 48 (Result field) 

• Columns 49 through 51 (Field length) 

• Column 52 (Decimal positions) 

• Column 53 (Half adjust) 

• Columns 54 through 59 (Resulting indicators) 

3.8.2 TAG 

TAG identifies the line to which program control from a GOTO operation branches. Factor 
1 contains the same label you used in Factor 2 of the GOTO operation. 

You cannot use conditioning indicators (columns 9 through 17) to condition a TAG opera¬ 
tion; however, you can use a control-level indicator if the TAG is in total-time calculations. 
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3.8.3 Example 

In the following example, RPGII branches to line 66 if indicators 67, 68, and 69 are on. 
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3.9 LOKUP Operation Code 

LOKUP searches for an entry in a table or an array. Factor 1 contains the search argument 
and Factor 2 contains the name of the table or array. The search argument can be an alpha¬ 
numeric or a numeric constant, a field name, an array element, or a table name. Search 
arguments must be the same length and format as the entries in the table or array For 
example, both fields must be numeric with the same number of digits, or both must be 
alphanumeric with the same number of characters. 

You must use at least one, but not more than two, resulting indicators to specify: 

• The type of search (high, low, or equal) 

• The result of the search (successful or not successful) 

The following list describes the three types of searches: 

• A resulting indicator in columns 54 and 55 causes RPG II to search the table or array 
for the entry that is nearest to but higher in sequence than the search argument. You 
can specify this search only for sequenced tables and arrays. 

• A resulting indicator in columns 56 and 57 causes RPG II to search the table or array 
for the entry that is nearest to but lower in sequence than the search argument. You 
can specify this search only for sequenced tables and arrays. 

• A resulting indicator in columns 58 and 59 causes RPG II to search the table or array 
for the entry that is equal to the search argument. 
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You can use two indicators to test for HIGH and EQUAL or LOW and EQUAL conditions. 
RPG II searches for an entry that satisfies either condition, with EQUAL given prece¬ 
dence. You cannot specify both HIGH and LOW conditions at the same time. 

If the search is successful, RPG II sets on the resulting indicator(s). If the search is not 
successful, RPG II sets off the resulting indicator(s). 

3.9.1 Searching Tables 

LOKUP can search one table or two related tables. When searching a single table, you 
must specify the following: 

• Factor 1 

• Factor 2 

• At least one resulting indicator 

You can specify conditioning indicators in columns 7 through 17. 

When RPG II finds a table entry that satisfies the type of search, it places a copy of the 
entry in a special storage area. If you repeat the search, the new entry replaces the previ¬ 
ous entry in the storage area. 

When searching for an entry in two related tables, RPG II searches only the table specified 
in Factor 2. When the search condition is satisfied, RPG II places the corresponding entries 
in their respective storage areas. 

To program a search for an entry in related tables, you must make the following entries: 

• Specify the search argument in columns 18 through 27 (Factor 1). 

• Specify the name of the table to be searched in columns 33 through 42 (Factor 2). 

• Specify the name of the related table in columns 43 through 48 (Result field). 

• Specify at least one resulting indicator in columns 54 through 59 (Resulting 
indicators). 

You can specify conditioning indicators in columns 9 through 17. 

Both tables should have the same number of entries. The related table must have as many 
entries as or more entries than the table to be searched. 

Whenever you use a table name in an operation other than a LOKUP operation, the table 
name refers to the data placed in storage by the last successful LOKUP operation. Then, 
you can use the table entry in subsequent calculations. If you specify a table name in an 
operation other than a LOKUP operation but before a successful LOKUP operation occurs, 
unpredictable results can happen. 
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If you specify the table name as Factor 1 in a LOKUP operation, the contents of the storage 
area are used as the search argument. 

You can also use a table as the Result field in operations other than LOKUP. In this case, 
the contents of the storage area are replaced by the result of the calculation you specify. 
The corresponding entry in the table is also changed. In this way, you can use calculations 
to change the contents of tables. 

In the following example, TABLIS has been previously defined as a table. RPGII searches 
for the entry that has the same value as the field PARTNO and, if successful, sets indicator 
33 on. 
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3.9.2 Searching Arrays 

LOKUP operations for arrays are the same as those for tables, except that you cannot use 
the Result field. If the element searched for is found, its contents are not moved to a storage 
area. Indicators reflect whether the element is present. 

To program a search for an element in an array, you must specify the name of the array to 
be searched in columns 33 through 42 (Factor 2). Follow the same rules for specifying 
indicators for arrays as for tables. 

You can specify the element to begin searching by adding an index. The index can be a 
numeric literal or a field. RPG II begins searching at the specified element and continues 
the search until it finds the element or it reaches the end of the array. If you use a numeric 
literal to specify the index, RPG II does not change its value to reflect the result of the 
search. If you use a field to specify the index and the search is not successful, RPG II places 
the value of 1 in the field. If you use a field to specify the index and the search is successful, 
RPG II places the number of that array element that satisfied the search (counting from 
the first element) in the field. Then, you can use the index field to reference that array 
element in subsequent operations. 
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If you use an index that is less than or equal to zero, or greater than the number of ele¬ 
ments in the array, and you compile the program with the RPG/CHECK = BOUNDS com¬ 
mand, RPGII issues a run-time error. If you use an index that is less than or equal to zero, 
or greater than the number of elements in the array, and you do not compile the program 
with the RPG/CHECK = BOUNDS command, unpredictable results can occur. 

3.9.3 Example 

In the following example, MNTH has been previously defined as a sequenced array and E 
as a numeric field. RPG II begins searching with the first element of the array, because 1 is 
assigned to E, and searches for the first entry with a value that is greater than and equal to 
1000. If an entry is found, E will contain the index number of the entry and the indicator 99 
will be set on. If an entry is not found, E will contain 1 and the indicator 99 will be set off. 
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3.10 Subprogram Operation Codes 

RPG II programs can call subprograms written in other languages and can pass and 
receive parameters between the main program and the subprogram. See Part I, Chapter 9 
for examples of subprogram operation codes. 

3.10.1 CALL 

CALL transfers control to a subprogram. Factor 2 contains a character literal or a field 
defined by the EXTRN operation code that names the entry point in the subprogram. 

The Result field can contain the name of the parameter list associated with the PLIST 
operation code. This way, you can share parameters between the main program and the 
subprogram. You can also specify the individual parameters immediately following the 
CALL operation code. 
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Factor 1, Half adjust, and the resulting indicators in columns 54 and 55, and 58 and 59, 
must be blank. However, you can specify a resulting indicator in columns 56 and 57. 
RPGII sets this indicator on when the subprogram returns with an error status. 

3.10.2 EXTRN 

EXTRN initializes the value of a numeric unsealed field to a link-time constant. You can 
use EXTRN to perform the following operations: 

• Extend the subprogram name to more than eight characters. 

• Allow your program to access link-time constants, including status codes. 

You define link-time constants using external names. Use Factor 1 to name the field 
RPG II initializes, using the value of the link-time constant. Use Factor 2 to name the 
external constant. You can use up to 31 characters to name the constant. You must enclose 
the constant in apostrophes. 

The external name must be defined as a global symbol in an object module available to the 
program at link time. Otherwise, an error will occur at link time. 

Factor 1 of the EXTRN operation is defined as a nine-digit numeric field with zero Decimal 
positions. The field cannot be defined elsewhere in the program. Fields defined by an 
EXTRN operation cannot be used as a Result field in a calculation or have Blank after 
specified when used on an Output specification. 

Conditioning indicators must be left blank. 

3.10.3 GIVNG 

GIVNG allows you to define a parameter that receives the return status from the sub¬ 
program. (See the VAX/VMS Run-Time Library Routines Reference Manual for informa¬ 
tion on the definition of return status.) GIVNG must follow the last PARM, PARMV, and 
PARMD operation following a CALL operation. The Result field contains the name of a 
unsealed numeric field, table, or array element. 

Entries in Decimal positions and Field length are optional. If you specify a Field length, 
the entry for Decimal positions must be zero. The following columns must be left blank: 

• Columns 9 through 17 (Conditioning indicators) 

• Columns 18 through 27 (Factor 1) 

• Columns 33 through 42 (Factor 2) 

• Column 53 (Half adjust) 

• Columns 54 through 59 (Resulting indicators) 


3-26 Operation Codes 



3.10.4 PARM 


PARM passes parameters by reference to a subprogram. The Result field identifies the 
parameter. The parameter can be a field, a table, an array element, or an array. Factor 2 
can contain a field, a table, an array element, an array, or a literal. The contents of Factor 2 
are copied into the Result field before the subprogram is called. If the Result field is 
numeric, Factor 2 must be numeric. In this case, the value in Factor 2 is copied into the 
Result field in the same manner as a Z-ADD operation. If the Result field is alphanumeric, 
Factor 2 must be alphanumeric. In this case, the value is left-justified in the Result field 
and trailing characters are filled with blanks. 

The subprogram can change the contents of the Result field but cannot change the contents 
of Factor 2. Using Factor 2 allows you to pass the values from Factor 2 knowing that the 
subprogram cannot modify the field. 

After a successful CALL operation, RPGII copies the contents of the parameter into Factor 
1. Factor 1 can contain a field, a table, an array, or an array element. The copying is done in 
the same manner as for Factor 2. Entries for Factor 1 and Factor 2 are optional. 

Entries in Decimal positions and Field length are optional. Conditioning indicators must 
be left blank. RPG II, by default, passes numeric data by reference in packed decimal 
format. 

You can also use PARM to convert to the numeric data type needed by the subprogram 
being called. Use columns 54 through 59 (Resulting indicators) to specify the notation for 
the parameter. See Part I, Chapter 9 for information on specifying parameters. 

You can use one of the following access types: 

• R (Read only) 

The parameter is read by the subprogram(s), but not modified. 

• W (Write only) 

The parameter is not read by the subprogram(s), but a new value is supplied by the 
subprogram. 

• M (Modify) 

The parameter is read by the subprogram(s) and a new value is supplied by the 
subprogram. 
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You can use one of the following data types: 

• W (Word integer (signed)) 

• L (Longword integer (signed)) 

• Q (Quadword integer (signed)) 

• F (F_floating single-precision) 

• D (D_floating double-precision) 

• NRO (Numeric string, right overpunched sign) 

See Part II, Chapter 1 for information on data types. 

You cannot specify an access type or data type if the Result field is an entire array 
(nonindexed). 

3.10.5 PARMD 

PARMD passes parameters by descriptor to a subprogram. The Result field contains the 
name of the field, the name of an array element, the name of the array, or a literal that 
identifies the parameter. Long character literals can be used effectively in the PARMD 
result field. See Part II, Section 2.9.5 for information on long character literals. 

Entries in Decimal positions and Field length are optional. The following columns must be 
left blank: 

• Columns 9 through 17 (Conditioning indicators) 

• Columns 18 through 27 (Factor 1) 

• Columns 33 through 42 (Factor 2) 

• Column 53 (Half adjust) 

• Columns 54 through 59 (Resulting indicators) 

See the VAX/VMS Run-Time Library Routines Reference Manual for information on argu¬ 
ment descriptor format. 

3.10.6 PARMV 

PARMV passes parameters by value to a subprogram. The Result field contains the name 
of an unsealed numeric field, table, array, or an unsealed numeric literal that identifies the 
parameter. 


3-28 Operation Codes 



Entries in Decimal positions and Field length are optional. If you specify a Field length, 
the entry for Decimal positions must be 0. The following columns must be left blank: 

• Columns 9 through 17 (Conditioning indicators) 

• Columns 18 through 27 (Factor 1) 

• Columns 33 through 42 (Factor 2) 

• Column 53 (Half adjust) 

• Columns 54 through 59 (Resulting indicators) 

3.10.7 PLIST 

PLIST identifies the name of the parameter list for a subprogram. Use this operation code 
with the CALL operation code to access parameters in the subprogram. You can pass up to 
255 parameters. 

Factor 1 contains the name of the parameter list. The following columns must be left 
blank: 

• Columns 9 through 17 (Conditioning indicators) 

• Columns 33 through 42 (Factor 2) 

• Columns 43 through 48 (Result field) 

• Columns 49 through 51 (Field length) 

• Column 52 (Decimal positions) 

• Column 53 (Half adjust) 

• Columns 54 through 59 (Resulting indicators) 

If you want to pass parameters, you must use one of the parameter operation codes (PARM, 
PARMD, PARMV) to specify how you want to pass the parameters. Parameter operation 
codes must immediately follow the CALL or PLIST operation. And, parameter operation 
codes must be in the order expected by the subprogram. 
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3.10.8 Example 

The following example makes a call to the STR$UPCASE RTL routine. The call places 
REP HEAD in the Result field RESULT. 

Field length 


Control level 

1 

1 Indicators 

Operation 

1 

i 

i 

i 

Decimal positions 

IHalf adjust (H) 

II 

1 1 

i 

11 Resulting 

1 1 Factor 

1 Factor 

Result 1 

11 indicators 

1 1 1 

1 2 

field 1 

11+ - 0 

)\ NxxNxxNxxl 

1 1 

1 1 

ll> < = +- Comments — 


0 I i I 2 I 3 1 4 I 5 16 17 1 

12345678901234567890123456789012345678901234567890123456789012345678901234567890 


## # # # # # #—### # # # 

C MOVE 'rep head'HEAD 8 

C UPCASE EXTRN'STR$UPCASE' 

C CALL UPCASE 

C PARMD RESULT 8 

C PARMD HEAD 

ZK-4529-85 
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Table 3-1: Summary of Operation Codes 


Indicators 


Operation Factor 1 Factor 2 Result Control Conditioning Resulting 

Code Field Level + > - < 0 = 


28-32 

18-27 

33-42 

43-48 

7-8 

9-17 

54-55 

56-57 

58-59 

ADD <H) 

0 

R 

R 

0 

0 

0 + 

0 - 

OO 

BEGSR 

R 








BITOF 


R 

R 

0 

0 




BITON 


R 

R 

0 

0 




CALL 


R 

0 

0 

0 


OE 


CHAIN 

R 

R 


0 

0 

ONR 


ORL 

COMP 1 

R 

R 


0 

0 

OH 

OL 

OEQ 

DIV (H) 

0 

R 

R 

0 

0 

0 + 

0 - 

OZ 

DSPLY 

0 

R 

0 

0 

0 




ENDSR 

0 








EXCPT 


0 


0 

0 




EXSR 


R 


0 

0 




EXTRN 

R 

R 


0 





FORCE 


R 


0 

0 




GIVNG 



R 

0 





GOTO 


R 


0 

0 




LOKUP 1 A 

R 

R 


0 

0 

OH 

OL 

OEQ 

LOKUP 1 T 

R 

R 

0 

0 

0 

OH 

OL 

OEQ 

MOVE 


R 

R 

0 

0 




MOVEA 


R 

R 

0 

0 




MOVEL 


R 

R 

0 

0 




MULT <H) 

0 

R 

R 

0 

0 

O + 

0 - 

OZ 

MVR 



R 

0 

0 

0 + 

0 - 

OZ 

PARM 

0 

0 

R 

0 





PARMD 



R 

0 





PARMV 



R 

0 





PLIST 

R 



0 





READ 


R 


0 

0 



0 EOF 

SETLL 

R 

R 


0 

0 





(continued on next page) 
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Table 3—1: Summary of Operation Codes (Cont.) 


Operation 

Code 

Factor 1 

Factor 2 

Result 

Field 



Indicators 



Control 

Level 

Conditioning 

+ > 

Resulting 

- < 

0 = 

28-32 

18-27 

33-42 

43-48 

7-8 

9-17 

54-55 

56-57 

58-59 

SETOF 1 




0 

0 

0 

0 

0 

SETON 1 




0 

0 

0 

0 

0 

SQRT (H) 


R 

R 

0 

0 




SUB (H) 

0 

R 

R 

0 

0 

0 + 

0 - 

oz 

TAG 

R 



0 





TESTB 1 


R 

R 

0 

0 

0 

0 

0 

XFOOT' H) 


R 

R 

0 

0 

0 + 

0 - 

oz 

Z-ADD (H) 


R 

R 

0 

0 

0 + 

0 - 

oz 

Z-SUB (H) 


R 

R 

0 

0 

0 + 

0 - 

oz 


(H) You can specify Half adjust for this operation. 

1 Specify at least one resulting indicator for this operation. 

Conditioning indicators are valid only for executable operation codes. 
Fields without entries in this table must be blank. 

(A) Factor 2 is an array. 

(T) Factor 2 is a table. 


Legend 

+ = positive 
E = error 
NR = no record 
ZB = zero or blank 


- = negative 
EQ = equal 
R = required 
RL = record locked 


EOF = end of file 
O = optional 
Z = zero 
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Character Sets 


Character Sets 


ASCII 

Character Decimal Hexadecimal 

EBCDIC 

Decimal Hexadecimal 

NUL 

000 

00 

000 

00 

SOH 

001 

01 

001 

01 

STX 

002 

02 

002 

02 

ETX 

003 

03 

003 

03 

EOT 

004 

04 

055 

37 

ENQ 

005 

05 

045 

2D 

ACK 

006 

06 

046 

2E 

BEL 

007 

07 

047 

2F 

BS 

008 

08 

022 

16 

HT 

009 

09 

005 

05 

LF 

010 

0A 

037 

25 

VT 

Oil 

0B 

Oil 

OB 

FF 

012 

OC 

012 

OC 

CR 

013 

OD 

013 

OD 

SO 

014 

OE 

014 

OE 

SI 

015 

OF 

015 

OF 

DLE 

016 

10 

016 

10 

DC1 

017 

11 

017 

11 

DC2 

018 

12 

018 

12 

DC3 

019 

13 

019 

13 

DC4 

020 

14 

060 

3C 

NAK 

021 

15 

061 

3D 

SYN 

022 

16 

050 

32 

ETB 

023 

17 

038 

26 

CAN 

024 

18 

024 

18 


(continued on next page) 
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Character Sets 


ASCII EBCDIC 

Character Decimal Hexadecimal Decimal Hexadecimal 


EM 

025 

19 

025 

19 

SUB 

026 

1A 

063 

3F 

ESC 

027 

IB 

039 

27 

FS 

028 

1C 

028 

1C 

GS 

029 

ID 

029 

ID 

RS 

030 

IE 

030 

IE 

US 

031 

IF 

031 

IF 

space 

032 

20 

064 

40 

f 

033 

21 

079 

4F 

“ 

034 

22 

127 

7F 

# 

035 

23 

123 

7B 

$ 

036 

24 

091 

5B 

% 

037 

25 

108 

6C 

& 

038 

26 

080 

50 


039 

27 

125 

7D 

( 

040 

28 

077 

4D 

) 

041 

29 

093 

5D 

* 

042 

2A 

092 

5C 

+ 

043 

2B 

078 

4E 


044 

2C 

107 

6B 

— 

045 

2D 

096 

60 


046 

2E 

075 

4D 

/ 

047 

2F 

097 

61 

0 

048 

30 

240 

F0 

1 

049 

31 

241 

FI 

2 

050 

32 

242 

F2 

3 

051 

33 

243 

F3 

4 

052 

34 

244 

F4 

5 

053 

35 

245 

F5 

6 

054 

36 

246 

F6 

7 

055 

37 

247 

F7 

8 

056 

38 

248 

F8 

9 

057 

39 

249 

F9 


058 

3A 

122 

7A 

• 

059 

3B 

094 

6E 

< 

060 

3C 

076 

4C 

= 

061 

3D 

126 

7E 

> 

062 

3E 

110 

6E 

? 

063 

3F 

111 

6F 

@ 

064 

40 

124 

7C 


(continued on next page) 
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Character Sets 


ASCII 

Character Decimal Hexadecimal 

EBCDIC 

Decimal Hexadecimal 

A 

065 

41 

193 

Cl 

B 

066 

42 

194 

C2 

C 

067 

43 

195 

C3 

D 

068 

44 

196 

C4 

E 

069 

45 

197 

C5 

F 

070 

46 

198 

C6 

G 

071 

47 

199 

C7 

H 

072 

48 

200 

C8 

I 

073 

49 

201 

C9 

J 

074 

4A 

209 

D1 

K 

075 

4B 

210 

D2 

L 

076 

4C 

211 

D3 

M 

077 

4D 

212 

D4 

N 

078 

4E 

213 

D5 

0 

079 

4F 

214 

D6 

P 

080 

50 

215 

D7 

Q 

081 

51 

216 

D8 

R 

082 

52 

217 

D9 

s 

083 

53 

226 

E2 

T 

084 

54 

227 

E3 

U 

085 

55 

228 

E4 

V 

086 

56 

229 

E5 

W 

087 

57 

230 

E6 

X 

088 

58 

231 

E7 

Y 

089 

59 

232 

E8 

Z 

090 

5A 

233 

E9 

[ 

091 

5B 

074 

4A 

\ 

092 

5C 

224 

E0 

] 

093 

5D 

090 

5A 

A 

094 

5E 

095 

5F 


095 

5F 

109 

6D 

t 

096 

60 

121 

79 

a 

097 

61 

129 

81 

b 

098 

62 

130 

82 

c 

099 

63 

131 

83 

d 

100 

64 

132 

84 

e 

101 

65 

133 

85 

f 

102 

66 

134 

86 

g 

103 

67 

135 

87 

h 

104 

68 

136 

88 

i 

105 

69 

137 

89 


(continued on next page) 
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Character Sets 


Character 

ASCII 

Decimal 

Hexadecimal 

EBCDIC 

Decimal 

Hexadecimal 

j 

106 

6A 

145 

91 

k 

107 

6B 

146 

92 

1 

108 

6C 

147 

93 

m 

109 

6D 

148 

94 

n 

110 

6E 

149 

95 

0 

111 

6F 

150 

96 

P 

112 

70 

151 

97 

q 

113 

71 

152 

98 

r 

114 

72 

153 

99 

s 

115 

73 

162 

A2 

t 

116 

74 

163 

A3 

u 

117 

75 

164 

A4 

V 

118 

76 

165 

A5 

w 

119 

77 

166 

A6 

X 

120 

78 

167 

A7 

y 

121 

79 

168 

A8 

z 

122 

7A 

169 

A9 

{ 

123 

7B 

192 

CO 

1 

124 

7C 

106 

6A 

} 

125 

7D 

208 

DO 

~ 

126 

7E 

161 

A1 

DEL 

127 

7F 

007 

07 
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Appendix B 

Differences Between VAX RPGII and PDP-11 RPGII 


This appendix describes the following: 

• PDP-11 RPG II functionality that is not supported by VAX RPG II 

• VAX RPG II functionality that is supported in a different manner from PDP-11 
RPG II 

• Additional functionality that is supported only by VAX RPG II Version 1 and later 
versions. 

This appendix does not list these new features which have been added to VAX RPG II Ver¬ 
sion 2. See the on-line release notes for details of these new features. 

VAX RPG II does not support the following PDP-11 RPG II functionality: 

• Control specification (H) 

- Column 11 (Listing options) - The equivalent functionality is implemented using 
the LIST qualifier to the DCL RPG command. 

- Column 15 (Debug) - The DEBUG operation code is not supported. Instead, use the 
VAX/VMS Symbolic Debugger. 

- Column 25 (Source listing) - A single page size for the listing is supported. 

• Extension specification (E) 

- Columns 11 through 18 (From file name) - PDP-11 RPG II allows the same table 
input file to be specified for more than one pre-execution-time table or array. VAX 
RPG II requires a different file for each pre-execution-time table or array. 

• Calculation specification (C) 

- Columns 28 through 32 (Operation) - The DEBUG operation code is not supported. 

• Output specification (O) 

- Column 39 (Blank after) - Specifying Blank after for a constant field is not sup¬ 
ported. 
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• General 


- VAX RPGII uses PRN format files for printer output files. This format requires that 
you use the NOFEED qualifier with the PRINT command when printing printer 
output files. 

- PDP-11 RPG II handles both zoned numeric and overpunched decimal data for¬ 
mats for input transparently. VAX RPG II supports only overpunched decimal data 
format. 

- All user-defined names must be unique in VAX RPG II. 

- VAX RPG II does not support the HO indicator. Errors detected by VAX RPG II 
result in run-time errors. 

- VAX RPG II does not recognize LO as an indicator. While LO can be used as a control 
level in columns 7 and 8 of the Calculation specification, it cannot be used in an 
Output specification. 

VAX RPG II supports the following functionality differently from PDP-11 RPG II: 

• File specification (F) 

- Column 15 (File type) - When O (output) is entered in column 15 and column 66 
(File addition) does not contain A, VAX RPG II always creates a new version of the 
file, even if the file is an indexed or direct file. PDP-11 RPG II accesses an existing 
indexed or direct file if the specified file is found. 

- Columns 40 through 46 (Device code) - VAX RPG II uses the device code to define 
the functions that can be performed on the associated file. It does not refer to a spe¬ 
cific device. 

- Columns 47 through 52 (Symbolic device) - VAX RPG II uses the symbolic device in 
conjunction with the file name specified in columns 7 through 14 (File name) to 
associate the VAX RPG II file name with the VAX/VMS file specification. 

If you specify a symbolic device on the File Description specification and no VMS 
logical name translation exists for that symbolic device, then RPG II will have RMS 
use the symbolic device as the file name. 

If a symbolic device consists of all blanks, then RMS will act as if the symbolic 
device did not exist (for example, an attempt will be made to translate the file name 
as a logical name). The symbolic device may consist of any characters and will be 
passed to RMS when the file is opened. 
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In general, the file name will be translated as a logical name, if possible, if a sym¬ 
bolic device is not supplied. The hierarchy by which the file name is constructed by 
RMS is as follows: 

1. File name (symbolic device) 

2. Default File name (VAX RPGII file name) 

3. Related file name (DAT file type) 

The related file name can be overridden by supplying a different file type for the 
symbolic device. 

- Column 68 (Share) - VAX RPG II requires you to specify S to open a file for shared 
access. PDP-11 RPG II requires you to use the MULTIUSER qualifier with 
RPGASN. 

Input specification (I) 

- Column 43 (Data format)-When loading an execution-time array from an Input 
specification that is in packed decimal or binary format, VAX RPG II requires P 
(packed decimal) or B (binary) in column 43 of the Input specification. PDP-11 RPG 
II requires P (packed decimal) or B (binary) in column 43 on the Extension specifi¬ 
cation. 

Calculation specification (C) 

- A READ operation code on a file that has not been opened because it was condi¬ 
tioned by an external indicator that was off sets on the end-of-file indicator if one is 
specified. In this case, PDP-11 RPG II does not set on the end-of-file indicator. 

- VAX RPG II MOVE and MOVEL semantics are not exactly the same as those of 
PDP-11 RPG II, when the Result field is numeric. The differences are the following: 

• VAX RPG II does not perform the “spurious sign” and “sign ignored” cases of 
PDP-11 RPG II. 

• When the sending field is a character field, VAX RPG II converts the characters in 
the sending field in the following manner: 

- All valid overpunched decimal characters are converted to the sign and digit 
they represent. 

- All other characters are converted to a positive zero (+ 0). 

• If a READ operation is done before a SETLL operation, VAX RPG II will read the 
record with the lowest key. PDP-11 RPG II reads a record containing blanks in 
this case. 
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• PDP-11 RPGII does not issue any error when the DSPLY operation code is used 
with a field that is larger than the File record length. VAX RPG II issues an error 
in this case. 

• VAX RPG II will display (DSPLY operation code) the sign of a negative numeric. 

• Output Specification (O) 

- Columns 17 and 18 (Space) - PDP-11 RPG II assumes a single Space after if the 
entries in columns 17 and 18 are left blank or are zero. VAX RPG II assumes a sin¬ 
gle Space after only if all entries in columns 17 through 22 are left blank. Making 
an entry of zero in columns 17 and 18 allows overprinting. 

• General 

- ALTSEQ records - VAX RPG II uses hexadecimal representation to specify the 
entries in ALTSEQ records. PDP-11 RPG II uses octal representation. 

- Tables - For VAX RPG II, a reference to a table before the first LOKUP operation 
will locate the first element in the table. PDP-11 RPG II returns a blank. 

- VAX RPG II and PDP-11 RPG II support two-word (4-byte) binary data. PDP-11 
RPG II places the words in reverse order to what is required by VAX architecture. 
PDP-11 RPG II data files that include two-word (4-byte) binary data will require 
conversion to be used by VAX RPG II. 

- VAX RPG II uses the logical name RPG$UDATE to specify UDATE and uses the 
logical name RPG$EXT_INDS to specify the settings for external indicators. 

- PDP-11 RPG II treats blanks in a numeric field in overpunched decimal format 
as zeros. VAX RPG II does the same when you use the 
CHECK = BLANKS_IN_NUMERICS qualifier with the RPG command. 

- VAX architecture reports a reserved operand fault when invalid data is found in a 
numeric field. In VAX RPG II, this causes a run-time error. PDP-11 RPG II 
processes invalid numeric data without halting program execution. 

- PDP-11 RPG II’s run-time system changes the name of the process to the program 
name while the program is running. VAX RPG II will not do this. 
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- When compiling with RPG [FOO]TEST.RPG, PDP-11 RPG II places the .OBJ, 
.LST, .CMD, and .ODL files in the [FOO] directory, no matter what the current 
default directory is. 

VAX RPG II places the .OBJ and .LIS files into the default directory in a manner 
similar to other VAX languages. This VAX RPG II operation is similar to the follow¬ 
ing PDP-11 command lines: 

$ MCR PD PR PG 

RPG>TEST=CFOO]TEST.RPG 

RPG >CTRL/Z 

The above commands cause PDP-11 RPG II to place the files in the current default 
directory. 

Use the following command to simulate the PDP-11 RPG II operation: 

$ RPG [F0Q3TEST/LIS/0BJ 

- NOLIST is the default for invoking the VAX RPG II compiler interactively. PDP-11 
RPG II produces a listing file by default. 

Note that RPGDMP is not provided with VAX RPG II. A similar functionality is provided 
with the VMS utilities DUMP and SORT/MERGE. See the VAX/VMS DCL Dictionary for 
information on DUMP and SORT/MERGE. See the VAX/VMS Utilities Reference Volume 
for information on the three SORT qualifiers CONDITION, FIELD, and INCLUDE. 

VAX RPG II supports the following additional functionality: 

• Control Specification (H) 

- A Control specification (H) is not required. 

- Column 18 (Currency symbol) - You can specify the character to represent the cur¬ 
rency symbol. 

- Column 21 (Inverted print) - An entry of I, D, or J switches the function of decimal 
point and comma notation in numeric literals and edited formats, and changes the 
format of UDATE to day, month, and year (ddmmyy). 

• File Specification (F) 

- Columns 7 through 14 (File name) - File names can be up to eight characters. 

- Column 16 (File designation) - VAX RPG II does not require a primary file. 

- Column 19 (File format) - You can specify V to indicate that the file contains varia¬ 
ble-length records. 

- Columns 24 through 27 (Record length) - VAX RPG II allows all files, with the 
exception of display files, to have a record length of up to 9999 characters. 
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• Extension Specification (E) 

- The definition of compile-time tables and arrays can be mixed with the definition of 
execution-time and pre-execution-time tables and arrays. 

• Input Specification (I) 

- Columns 15 and 16 (Sequence) - You can specify input records with an alphabetic 
sequence before or after input records with a numeric sequence. 

- Columns 19 and 20 (Record-identifying indicator) - You do not have to specify look¬ 
ahead fields as the last record in a file. 

• Calculation Specification (C) 

- Columns 28 through 32 (Operation) - The following operations have been added to 
allow VAX RPG II programs to call subprograms written in other languages, rou¬ 
tines in the VAX Common Run-Time Library, and system services: 

• CALL - Calls a subprogram with optional parameters 

• PARM - Passes a parameter by reference 

• PARMD - Passes a parameter by descriptor 

• PARMV - Passes a parameter by value 

• GIVNG - Returns the status of a subprogram 

• EXTRN - Equates a VAX RPG II name with an external link-time constant 

• PLIST - Defines a parameter list 

- Columns 28 through 32 (Operation) - VAX RPG II allows Factor 2 and the Result 
field to reference the same array on a MOVE A operation. 

- Columns 49 through 52 (Field definition) - You do not have to define fields before 
they are used, as long as they are defined within the program. 

• Output Specification (O) 

- Columns 16 through 18 (ADD/DEL) - You can specify the DEL option to identify 
the record to be deleted. You can delete records from indexed or direct files. 

- Columns 45 through 70 (Edit word) - The number of replaceable characters in the 
Edit word can be greater than or equal to the number of digits in the numeric field. 
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• General 


- The string containing double slashes (//) and a blank and the string containing a 
double asterisk (**) and a blank are accepted as delimiters between specifications 
and any ALTSEQ records, and between compile-time tables and arrays. 

- The special words, *IN and *INxx, can be used to reference indicators as one-posi¬ 
tion character fields. 

- A user-defined name can contain a pound sign (#) and an underscore (_). 

- A character field can have a length of up to 9999 characters. 

The VAX RPGII editor does not support the following PDP-11 RPGII features: 

• Editing of SORT-11 specifications 

• VT05 or VT52 terminals 

• Hardcopy terminals 

• The following qualifiers: 

- IDENT 

- PAGE and NOPAGE 

- SAVE and NOSAVE 

- TERMINAL 

• CTRL/D 

• SET SKIP command 

• Automatically advancing the cursor to the next tab stop if the current field is full 

• Displaying a tab stop as data from an input file as the TAB character 

• Renaming the input file with a BAK file type 
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PCA Applied to an RPGII Program 


The following command procedure produces execution information by source line: 

$ r p S / d e b u s / n o 1 i s t ships 

$ 1ink/de bus = s ys $ 1ib r a r y:pc a $ o bJ♦o bJ/n o m a p ships 

$ run ships 

set datafile ships 

set counters program-address by line 
So 

$ pea ships 

tabulate/counters/source module ships by line 

file pc a ♦ 1 i s 

exit 

$ type pea*1 is 
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The Programming in VAX RPGII manual is comprised of two parts. References to Part I, 
which contains programming information, are preceded by a I. References to Part II, which 
contains language reference information, are preceded by a II. 


A 

Access mechanism, 79-23 
ADD operation code, 773-2 
example, II 3^t 
ADD option, II 2-95 
example, II 2-95 
rules for specifying, II 2-95 
Adding records, 1 5—22 
Addition operation, II 3-2 
Additional I/O area, II 2-28 
rules for specifying, II 2-28 
ADDROUT files 
creating, 1 5—14 
example, 1 5-15, 5-17 
function, 1 5-14 
rules for specifying, 1 5-16 
specifying 
Key length, II 2-27 
ADVANCE function, 1 3-20 
Alternate array, II 2-45 
Alternate collating sequence, II 2-13 to 2-14 
specifying 
example, II 2-14 
Alternate format 
arrays, 1 8-8 
compile-time, 1 8—8 
example, 7 8-9 
pre-execution-time, 1 8—8 
related, 1 8-8 
Alternate table, II 2-45 
AND, 7/2-61, 2-91 
example, II 2-62 
Output specification 
example, II 2-92 

rules for specifying, II 2-61, 2-91 
Arguments 
optional, 1 9-15 

Arithmetic operation codes, II 3-1 
ADD, 77 3-2 
blank Factor 1,77 3-2 
DIV, 77 3-3 
blank Factor 1,77 3-3 
example, 77 3-4 


Arithmetic operation codes, (Cont.) 
MULT, 77 3-3 
blank Factor 1,77 3-3 
MVR, 77 3-3 
rules, 77 3-1 
signs, 77 3-2 
SQRT, 77 3-4 
SUB, 77 3-3 
blank Factor 1,77 3-3 
XFOOTJ73-4 
Z-ADD, 77 3-2 
Z-SUB,77 3-3 
Array elements 
outputting, 7 8-21 
referencing, 7 8—15 
searching, 7 8-17 
XFOOT operation code, 7 8-15 
Arrays, 7 8-1 
addition operation, 77 3-4 
alternate format, 7 8-8,77 2-45 
compile-time, 7 8-2 
example, 7 8-3 
creating, 7 8^1 
array input records, 7 8-4 
definition, 7 8—1 
execution-time, 7 8^1 
in calculations, 7 8-10 
example, 78-11 
*IN indicators, 7 4-19 
*IN,n indicators, 7 4-19 
input records 
example, 7 8-4 
loading time 
selecting, 7 8-1 

LOKUP operation code, 7 8-15,77 3-24 
example, 7 8-16 
MOVEA operation code, 7 8-18 
example, 7 8-19 
moving data, 7 8-18,77 3-6 
example, 7 8-19 
names, 77 1-7 
outputting 

array elements, 7 8-21 
example, 78-21 



Arrays, outputting (Cont.) 
entire arrays, 78-20 
pre-execution-time, 78-4 
referencing, 7 8-10 
array elements, 78-10 
example, 78-15 
entire arrays, 7 8-10 
related, 7 8-5 

resulting indicators, 7 8-16 
searching, 7 8-15,77 3-24 
example, 7 8-16,77 3-25 
searching for elements, 7 8-17 
specifying, 7 8-5,77 2-18 
alternate format, 77 2-45 
Data format, 77 2-44 
Decimal positions, 77 2-44 
elements, 7 8-12 
From file name, 77 2-40 
Length of entry, 77 2-43 
names, 77 2^11 

Number of entries per record, 77 2-42 
Number of entries per table or array, 77 
2-42 

Sequence, 77 2-45 
To file name, 77 2-40 
transferring data, 77 3-6 
types 

compile-time, 7 8-2 
execution-time, 7 8-4 
pre-execution-time, 7 8-4 
updating, 78-19 
example, 7 8-20 
using, 7 8-1 
writing 

array elements, 7 8-21 
example, 7 8-21 
entire arrays, 7 8-20 
XFOOT operation code, 77 3-4 
example, 7 8-14 
ASCII character set, 77 A-l 
Asterisk protection, 77 2-113 
Automatic overflow, 7 6-13 


BACKUP function, 7 3-21 
BEGSR operation code, 77 3-10 
example, 77 3-10 
rules, 773-10 
Binary data types 
longword, 77 1-3 
specifying, 77 2-44 
word, 771-3 

Bit operation codes, 77 3-11 
BITOF, 77 3-12 
BITON, 77 3-11 
example, 77 3-12 


Bit operation codes, (Cont.) 

TESTB, 773-12 
BITOF operation code, 77 3-12 
example, 77 3-12 
rules, 773-12 

BITON operation code, 77 3-11 
example, 77 3-12 
rules, 77 3-11 
Bits 

setting off, 77 3-12 
setting on, 77 3-11 
testing, 77 3-12 
Blank after, 77 2-106 
example, 77 2-107 
rules for specifying, 77 2-106 
blank Factor 1 
example, 77 3-4 
Block length, 77 2-21 
rules for specifying, 77 2—22 
BOTTOM function, 7 3-21 
Branching operation codes, 77 
3-20 

example, 77 3-22 
GOTO, 77 3-20 
TAG, 77 3-21 
BS_KEY 
example, 7 3-56 
Buffers, 7 3-9 


c 

Calculation specification, 77 2-79 
Comments, 77 2-90 
Control-level indicators, 77 2-80 
Decimal positions, 77 2-87 
Factor 1,77 2-84 
Factor 2,77 2-84 
Field length, 77 2-87 
format, 77 2-79 
Half adjust, 77 2-88 
Indicators, 77 2-82 
long character literal, 77 2-84 
operation codes, 77 2-86, 3-1 
Result field, 77 2-86 
Resulting indicators, 77 2-88 
Type, 77 2-79 
Calculations 
arrays, 7 8-10 
documenting, 77 2-90 
operations 
addition, 77 3-2 
division, 77 3—3 
multiplication, 77 3-3 
square root, 77 3^1 
subtraction, 77 3-3 
referencing 

array elements, 7 8-10 
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Calculations, referencing (Cont.) 
entire arrays, 78-10 
Result field, II 2-86 
rounding data, II 2-88 
saving the remainder, II 3-3 
specifying 

Decimal positions, II 2-87 
Factor 1,7/2-84 
Factor 2, II 2-84 
Field length, II 2-87 
operation codes, II 2-86 
Resulting indicators, II 2-88 
totalling data, 1 4-15 
using indicators, II 2-82 
control-level, 1 4—9 
resulting, 1 4-6 
Call interface, 1 9-1 
subprograms, 1 9-32 
system services, 1 9-28 
CALL operation code, II 3-25 
example, II 3-30 
rules, II 3-25 
Calling 

RTL procedures, II 3-25 
subprograms, II 3-25 
system services, II 3-25 
Card reader device 
specifying, II 2-30 
CHAIN operation code, II 3-14 
example, II 3-15 

indicator for locked record, II 3-14 
reading records, II 3-14 
rules, II 3-14 
Chained files 
input 

selecting Mode of processing, II 2-25 
logic cycle, 1 1-18 
flowchart, 7 1-18 
update 

selecting Mode of processing, 77 2-25 
Character 

see record identification codes 
Character data type 
example, 77 1-2 

CHARACTER function, 7 3-26 
Character sets 
ASCII, 77 A-l 
Decimal, 77 A-l 
EBCDIC, 77 A-l 
Hexadecimal, 77 A-l 
CHECK qualifier, 7 2-A 
checking 

array boundaries, 7 2-5 
blanks in numeric fields, 7 2—5 
recursive calls to subroutines, 7 2-5 
format, 7 2-4 
options, 7 2-4 

BLANKS_IN_NUMERICS, 7 2-5 


CHECK qualifier, options (Cont.) 
BOUNDS, 7 2-5 
RECURSION, 7 2-5 
Collating sequences, 77 2-14 
Alternate, 77 2-13 
ASCII, 77 2-13 
EBCDIC, 77 2-13 
specifying 
example, 77 2-14 
COLUMN function, 7 3-26 
80-column ruler, 7 3-5 
definition, 7 3-7 
COMMAND function, 7 3-18 
example, 7 3-71 
Command line 
conditions, 7 3-29 
COMMAND qualifier, 7 3-2 
Commands 
DCL, 7 2-1 
debugger, 7 10-3 
RPG II editor, 7 3-18 
commands 
RUN, 7 2-9 

Comments, 77 2-5, 2-90 
rules for specifying, 77 2-5 
COMP operation code, 77 3-13 
example, 77 3-14 
rules, 77 3-13 
Compare operation codes 
COMP, 77 3-13 
Compile-time arrays, 7 8-2 
advantages, 7 8-2 
creating, 7 8-4, 8-6 
example, 7 8-6 
rules for specifying, 7 8-4 
example, 7 8-3 
outputting, 7 8-20 
updating, 7 8-19 
writing, 7 8-20 
Compile-time tables, 7 7-2 
advantage, 7 7—2 
example, 7 7-2 
input records 
creating, 7 7-3 
rules for specifying, 7 7-3 
outputting, 7 7-12 
rules for defining, 7 7-6 
searching 
example, 7 7—8 
writing, 7 7-12 

Compiler error messages, 7 2—9 
format, 7 2-9 
IDENT field, 7 2-9 
interpreting, 7 2-9 
Compiler listing, 7 11-1 
command qualifiers, 711-2 
copy directive, 7 11-1 
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Compiler listing, (Cont.) 
cross-reference information 
CROSS_REFERENCE qualifier, 711-1 
indicators, 711-2 
user-defined names, 711-1 
example, 711-3 
identification, 711-1 
interpreting, 711-1 
machine-generated code, 711-1 
MACHINE.CODE qualifier, 711-1 
PSECTs, 711-2 
source code, 7 11-1 
statistical information, 711-2 
Compiler options 
default, 7 2-2 
example, 7 2-2 
Compiling programs, 7 2-1 
example, 7 2-2 

generating an object module, 7 2-1 
specifying more than one 
program, 7 2-1 
Condition values 
returned, 7 9-20 
signaled, 7 9-20 
Constants, 77 2-111 
rules for specifying, 77 2-112 
Control breaks 
identifying, 7 4-8 
split-control fields, 7 4-11 
Control specification, 77 2-11 
Alternate collating sequence, 77 2-13 
Currency symbol, 77 2-12 
example, 77 2-15 
format, 77 2-12 
Forms position, 77 2-15 
Inverted print, 77 2-12 
Type, 77 2-12 

Control-level indicators, 7 4-8,77 2-71, 2-80 
conditioning data, 77 2-71 
control breaks, 7 4-9 
example, 7 4-10,77 2-73, 2-81 
function, 7 4—8 
hierarchy, 7 4-8 

identifying control breaks, 7 4-8 
rules for specifying, 77 2—72 
signaling changes in control fields, 7 4-8 
split-control fields, 7 4-11 
Copy from CDD, 77 2-7 
COPY qualifier, 77 2-7 
Core index, 77 2-31 
rules for specifying, 77 2-32 
CREATE qualifier, 7 3-3 
CROSS_REFERENCE qualifier, 7 2-5 
cross referencing 
indicators, 7 2-5 
user-defined fields, 7 2-5 
format, 7 2-5 


CROSS_REFERENCE qualifier, (Cont.) 
generating cross-reference information, 
711-1 

CTRL_Z_KEY 
example, 7 3-65 
Currency symbol, 77 2-12 
rules for specifying, 77 2-12 
Cursor, 7 3-8 
CUT function, 7 3-21 
example, 7 3-74 
CZD portion 

see record identification codes 


Data 

comparing contents, 77 3-13 
displaying, 77 3-16 
moving, 77 3-5 
moving from the left, 77 3-6 
repeating, 7 6-7 
transferring, 77 3-5 
Data formats 
binary, 77 2^14 

Extension specification, 77 2-44 
Input specification, 77 2-62 
Output specification, 77 2-109 
example, 77 2-109 
overpunched decimal, 77 2-44 
packed decimal, 77 2-44 
Data structure, 77 2-50 
Data structure subfield, 77 2-53 
Data structures, 77 2-52 
examples of using, 77 2-66 to 2-68 
local data area, 77 2-55 
examples, 77 2-69 
updating files, 7 5-26 
Data types, 77 1-1 
binary, 77 1-3 
character, 77 1-2 
overpunched decimal, 77 1-4 
packed decimal, 77 1-3 
specifying, 77 2-44 
Date 

formatting, 7 6-3 
printing, 7 6-3 
DCL commands 
RPG, 7 2-1 

DCL RPG command, 7 2-1 
default compiler options, 7 2-2 
qualifiers 

example, 7 2-3 to 2-4 
DEBUG qualifier, 7 2-6,10-1 
format, 7 2-6 
options, 7 2-6 
SYMBOLS, 7 2-6 
TRACEBACK, 7 2-6 
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DEBUG qualifier, (Cont.) 
providing 

an address correlation table, 72-6 
information for the VAX Symbolic 
Debugger, 72-6 
local symbol definitions, 72-6 
DEBUG qualifiers 
ALL, 710-1 
NONE, 710-1 
SYMBOLS, 710-1 
TRACEBACK, 710-1 
Debugger commands 
CANCEL BREAK, 7 10-6 
CANCEL TRACE, 7 10-7 
CANCEL WATCH, 710-9 
CTRL/Y, 7 10-12 
DEPOSIT, 710-14 
EDIT, 710-12 
EVALUATE, 710-15 
EXAMINE, 710-13 
EXIT, 710-12 
GO, 710-10 
SET, 710-7 

stepping through a TAG, 7 10-7 
stepping through subroutines, 7 10-7 
SET BREAK, 7 10-6 
SET LANGUAGE, 710-4 
SET STEP, 710-11 
SET TRACE, 710-7 
SET WATCH, 710-9 
SHOW BREAK, 710-6 
SHOW CALLS, 7 10-10 
SHOW LANGUAGE, 710-4 
SHOW TRACE, 710-7 
SHOW WATCH, 710-9 
STEP, 710-10 
qualifiers 
INTO, 710-10 
LINE, 710-10 
OVER, 710-10 
SOURCE, 710-10 
SYSTEM, 710-10 
TYPE, 710-11 

Debugging RPGII programs, 7 10-1 
debugger commands 
table, 710-3 

*DETC logic cycle label, 710-5 
*DETL logic cycle label, 710-5 
displaying source code, 7 10-11 
edit the file you are debugging, 710-12 
evaluating expressions, 7 10-15 
examining 

array elements, 7 10-6 
contents of 

array elements, 710-13 
I/O buffers, 710-13 
table entries, 710-13 
variables, 710-13 


Debugging RPG II programs, 
examining (Cont.) 
data, 7 10-6 
locations, 7 10-13 
table entries, 7 10-6 
executing program lines, 7 10-10 
*GETIN logic cycle label, 7 10-5 
leaving the debugger, 7 10-12 
modifying 

array elements, 7 10-6,10-14 
data, 7 10-6 
locations, 7 10-13 
table entries, 7 10-6 
variables, 7 10-14 
*OFL logic cycle label, 710-5 
referencing 
array elements, 7 10-6 
data, 7 10-6 
line numbers, 7 10-3 
logic cycle labels, 7 10-5 
table entries, 7 10-6 
resuming program execution, 710-10 
returning to system command level, 

7 10-12 
setting 

breakpoints, 7 10-6 
indicators, 710-14 
tracepoints, 710-7 
watchpoints, 7 10-9 
subprograms, 7 10-10 
suspending program execution, 7 10-7 
table entries, 710-14 
*TOTC logic cycle label, 710-5 
*TOTL logic cycle label, 710-5 
tracing calls, 7 10-10 
Decimal character set, 77 A-l 
Decimal positions, 77 2-44, 2-64, 2-87 
rules for specifying, 77 2-44, 2-64, 2-87 
Default compiler options, 7 2—2 
DEL option, 77 2-95 
example, 77 2-96 
rules for specifying, 77 2-95 
DELETE TO END OF LINE function, 7 3-25 
DELETE_CHARACTER Function, 7 3-28 
DELETE_FIELD function, 7 3-20 
DELETE_LINE function, 7 3-17 
DELETE _TO_BEGINNING_OF JUNE 
function, 7 3-29 

DELETE_TO_END_OF_LINE function 
example, 7 3-25 
Deleted-field buffer, 7 3-9 
Deleted-line buffer, 7 3-9 
Demand files 
logic cycle, 7 1-18 
flowchart, 7 1-18 
READ operation code, 77 3-19 
selecting Mode of processing, 77 2-24 
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Detail time, 71—2 

processing individual records, 71-5 
Developing programs 
creating 
example, 7 3-54 
generating a listing file, 711-1 
Device codes, II 2-30 
rules for specifying, II 2-30 
specifying 
card reader, II 2-30 
disk, II 2-30 
magnetic tape, II 2-30 
printer, II 2-30 
terminal, II 2-30 
Direct file organization, 1 5-3 
example, 1 5-3 
Direct files 

adding records, 7 5-24 
example, 1 5-24 to 5-25 
rules for specifying, 7 5—24 
creating, 1 5-20 
example, 1 5-21 
rules for specifying, 1 5-20 
updating records 
rules for specifying, 7 5-27 
Disk device 
specifying, II 2-30 
DISPLAY function, 1 3-19 
example, 1 3-62 
DIV operation code, II 3-3 
example, II 3^1 
Division operation, II 3-3 
saving the remainder, II 3-3 
DOWN function, 7 3-28 
DSPLY operation code, II 3-16 
displaying data, II 3-16 
example, II 3-17 
rules, II 3—16 


E 

EBCDIC character set, II A-l 
Edit code modifiers, II 2-110 
asterisk fill, 1 6-2 
example, II 2-111 
floating dollar sign, 1 6-2 
rules for specifying, II 2-110 
Edit codes, II 2-104 
combined, 1 6-1 
constants 
example, 1 6-2 
rules for specifying, 1 6-2 
example, II 2-106 
modifiers, 1 6-2 
printer output files, 1 6-1 
rules for specifying, II 2-105 
simple, 1 6-1 


Edit codes, (Cont.) 
specifying 
notation, II 2-12 
Edit words, II 2-112 
body, II 2-112 
example, II 2-114 
expansion, II 2-112 
rules for specifying, II 2-117 
sign status, II 2-112 
specifying 

asterisk protection, II 2-113 
blank spaces, II 2-114 
commas, II 2-115 
CR, 7/2-116 

currency symbol, II 2-114 
decimal points, II 2-115 
negative signs, II 2-116 
zero suppression, II 2-113 
editing buffer, 7 3-9 
editing window, 7 3—5 
Editor 
see RPGII 

End position, 77 2-107 
example, 77 2-108 
rules for specifying, 77 2-107 
End-of-file, 77 2-19 
rules for specifying, 77 2-20 
END_OF_LINE function, 7 3-24 
example, 7 3-24 
ENDSR operation code, 77 3-10 
example, 77 3-10 
rules, 77 3-10 
ENTER function, 7 3-26 
ENTER key 
example, 7 3-67 
EOB mark, 7 3-7 
Error messages 
compiler, 7 2-9 
IDENT field values, 7 2-10 
Errors 

handling, 74-17 
halt indicators, 7 4-17 
EXCPT 
names, 771-7 
EXCPT name, 77 2-103 
EXCPT operation code, 77 3-17 
writing records during 
calculations, 77 3-17 
Execution-time arrays, 7 8^ 
creating, 7 8^, 8-7 
example, 7 8-8 
rules for specifying, 7 8-4 
loading 

example, 7 8-8, 8-13 
outputting, 7 8-20 
example,/ 8-21 
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Execution-time arrays, (Cont.) 
specifying 

array elements 
example, 78-13 
entire arrays 
example, 78-13 to 8-14 
writing, 78-20 
example, 78-21 
EXIT function, 73-29 
Expansion factor, 772-33 
improving search efficiency, II 2-33 
preventing bucket splitting, II 2-33 
table, 77 2-34 

EXSR operation code, 77 3-10 
example, 77 3-10 
rules, 77 3-10 
Extension code, 77 2-29 
Extension specification 
Comments, 77 2^6 
Data format, 77 2-44 
Decimal positions, 77 2^4 
defining 

arrays, 77 2-38 
record-address files, 77 2-38 
tables, 77 2-38 
example, 77 2-46 
format, 77 2-39 
From file name, 77 2^0 
Length of entry, 77 2^3 
name of record-address file, 77 2^0 
name of table input file, 77 2-40 
Number of entries per record, 77 2-42 
Number of entries per table or array, 
77 2-42 

Sequence, 77 2^45 
Table or array name, 77 2-41 
To file name, 77 2-40 
Type, 77 2-40 

External indicators, 7 4—16 
controlling the opening of files, 7 4—16 
example, 7 4-16, 9-30 
function, 7 4—16 
setting, 7 4—16 
specifying, 7 4—16 
EXTRN operation code, 77 3-26 
accessing 

link-time constants, 77 3-26 
RTL status codes, 77 3-26 
example, 77 3-30 
RTL procedures, 77 3-26 
rules, 77 3-26 


Factor 1,77 2-84 
Factor 2,77 2-84 
Fetch overflow, 7 6-11,77 2-96 


Fetch overflow, (Cont.) 
example, 7 6-12,77 2-97 
rules for specifying, 7 6-11,77 2-96 
FIELD function, 7 3-23 
example, 7 3-23 
Field indicators, 7 4-4 
checking the condition of data 
fields, 77 2-78 

conditioning input data, 77 2-78 
example, 7 4-5 
function, 7 4-A 
rules for specifying, 77 2-78 
Field length, 77 2-87 
rules for specifying, 77 2-87 
Field locations, 77 2-63 
rules for specifying, 77 2-63 
Field name, 77 2-64, 2-102 
Input specification, 77 2-64 
example, 77 2-65 
rules for specifying, 77 2—64 
Output specification, 77 2-102 
example, 77 2-103 
rules for specifying, 77 2-102 
Field names, 77 1-6 

Field-record-relation indicators, 77 2-75 
conditioning input data, 77 2-75 
controlling data extraction, 77 2-75 
example, 77 2-77 
rules for specifying, 77 2-76 
using matching fields, 7 5-31 
example, 7 5-31 to 5-33 
FIELD .BACKWARD function, 7 3-28 
example, 7 3-56 

FIELD.FORWARD function, 7 3-29 
Fields 

common, 77 2-4 
defining locations, 77 2-63 
indicators, 7 4-4 
input 

specifying 

Decimal positions, 77 2-64 
look-ahead, 77 2-57 
matching, 7 5-29,77 2-73 
checking sequence, 77 2-20 
naming, 77 2-64 
repeating, 7 6-7 
specifying 

Data format, 77 2-62 
IN, 77 2-64 
IN,xx, 77 2-64 
length, 77 2-87 
PAGE special word, 77 2-64 
split-control, 7 4-11 
testing values, 7 4—4 
that require 
blanks, 77 2-3 
character values, 77 2-3 
numeric values, 77 2-3 
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Fields (Cont.) 

using indicators to compare 
contents, II 2-71 
File access methods 
random, / 5-11 
sequential, 1 5-6 
sequential by key, 1 5-7 
sequential within limits, / 5-8 
table, / 5-5 
File addition, II 2-32 
rules for specifying, II 2-33 
File condition, II 2-37 
File Description specification, II 2-16 
Additional I/O area, II 2-28 
Block length, II 2-21 
Core index, II 2-31 
Device code, II 2-30 
End-of-file, II 2-19 
example, II 2-38 
Expansion factor, II 2-33 
Extension code, II 2-29 
File addition, II 2-32 
File condition, II 2-37 
File designation, II 2-18 
File format, II 2-21 
File name, II 2-17 
File organization, II 2-28 
File sharing, II 2-35 
File type, II 2-17 
format, II 2-16 
Key length, II 2-27 
Key location, II 2-29 
Mode of processing, II 2-23 
Overflow indicators, II 2-29 
Record address type, II 2-28 
Record length, II 2-22 
Sequence, II 2-20 
Symbolic device, II 2-31 
Tape label, 7/2-31 
Tape rewind, II 2-37 
Type,// 2-16 
Unordered output, // 2-32 
File designations, II 2-18 
array,// 2-18 
chained, // 2-18 
demand, II 2-18 
full-procedural, II 2-18 
primary, II 2-18 
record-address, II 2-18 
secondary, II 2-18 
table, II 2-18 
File format, II 2-21 
rules for specifying, II 2-21 
File names, II 1-6 

File Description specification, II 2-17 
rules for specifying, II 2-17 
Input specification, II 2-51 
rules for specifying, II 2—51 


File names, (Cont.) 

Line Counter specification, II 2-48 
rules for specifying, II 2-48 
Output specification, II 2-91 
rules for specifying, II 2-91 
rules for specifying, / 5-1 
File organizations, II 2-28 
direct, 1 5-3 
indexed, 1 5^1 
sequential, 1 5-2 
File sharing, II 2-35 
rules for specifying, II 2-35 
File types, II 2-17 
display, II 2-17 
input, 1 5-2, II 2-17 
output, 1 5-2, II 2-17 
update,/5-2,//2-17 
Files 

adding records, 1 5-23 
ADDROUT, / 5-14 
specifying 
Key length, II 2-27 
CHAIN operation code, II 3-14 
changing processing order, 

II 3-18 

compiler listing, 1 11-1 
conditioning with an external 
indicator, II 2-37 
creating, 1 5-20 
ADDROUT,/5-15 
direct, 1 5-20 
indexed, 1 5-21 
output, / 6-1 
printer output, / 6-1 
record-limits, 1 5-8 
sequential, 1 5-20 
definition, 1 5-1 
deleting records, 1 5-28 
DSPLY operation code, II 3-16 
EXCPT operation code, II 3-17 
external indicators, 1 4-16 
file access methods, 1 5-5 
file names, 1 5—1 
file types, / 5-2 

FORCE operation code, II 3-18 
full-procedural, 1 5-18 
example, 1 5-19 

improving search efficiency, II 2-33 
indexed 
specifying 
Key length, II 2-27 
input 

specifying 

File addition, II 2-32 
Unordered output, II 2-32 
input/output operation codes, II 3-14 
matching-record indicators, 1 4-16 
multifile processing, 1 5-29 
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Files (Cont.) 
organization, 75-2 
output, 76-1 

controlling overflow, II 2-29 
using overflow indicators, II 2-29 
preventing bucket splitting, II 2-33 
printer output, 1 6-1 
controlling overflow, II 2-29 
using overflow indicators, II 2-29 
processing using matching 
fields, 7/2-73 
random access, 1 5-11 
random access by key, 1 5-18 
READ operation code, II 3-19 
reading record during 
calculations, II 3-14 
record formats, 1 5-2 
record-limits, 1 5-8 
specifying 

Key length, II 2-27 
sequential access, 7 5-6, 5-18 
sequential by key access, 7 5-7 
sequential within limits access, 7 5-8 
SETLL operation code, 77 3-19 
specifying 
chained, 77 2—18 
demand, 77 2-18 
display, 77 2-17 
full-procedural, 77 2-18 
input, 77 2-17 
Mode of processing, 77 2-23 
output, 77 2-17 
primary, 77 2-18 
record-address, 77 2-18 
secondary, 77 2-18 
update, 77 2-17 
update 
specifying 

File addition, 77 2-33 
Unordered output, 77 2-33 
updating records, 7 5-26 
FIND function, 73-17 
example, 7 3-67 
FIND_NEXT function, 7 3-16 
example, 7 3-69 

First-page indicators, 7 4-14, 6-8 
conditioning output data, 7 4-14 
example, 7 4-14, 6-9 
function, 74-14 
specifying, 7 4—14 
FL, 7/2^19 
FMS, 7 9-33 to 9-34 
FORCE operation code, 77 3-18 
changing file processing order, 77 3-18 
example, 77 3-18 
rules, 773-18 
selecting files, 77 3-18 
Form length, 77 2^19 
FL, 77 2-49 


Form length, (Cont.) 

rules for specifying, 77 2-49 
Forms alignment 
changing, 77 2-15 
Forms position, 77 2-15 
From file name, 77 2^0 
arrays, 77 2^0 
record-address files, 77 2-40 
rules for specifying, 77 2-40 
tables, 77 2-40 
Function 

SHIFT_RIGHT, 7 3-22 
Function calls 
for system routines, 7 9—15 
Functions, 7 3-9 to 3-10 
see RPGII editor 
ADVANCE, 7 3-20 
BACKUP, 7 3-21 
BOTTOM, 7 3-21 
CHARACTER, 7 3-26 
COLUMN, 7 3-26 
COMMAND, 7 3-18 
CUT, 7 3-21 

DELETE .CHARACTER, 7 3-28 
DELETE_FIELD, 7 3-20 
DELETE-LINE, 7 3-17 
DELETE_TO_BEGINNING_OF_LINE, 
73-29 

DELETE-TO-END-OF-LINE, 7 3-25 
DISPLAY, 7 3-19 
displaying specification 
formats, 7 3-14 
DOWN, 7 3-28 
END-OF-LINE, 7 3-24 
ENTER, 7 3-26 

executing editor commands, 7 3-18 
EXIT, 7 3-29 
FIELD, 7 3-23 

FIELD-BACKWARD, 7 3-28 
FIELD-FORWARD, 7 3-29 
FIND, 7 3-17 

specifying the search string, 7 3-17 
FIND-NEXT, 7 3-16 
finding the next occurrence of the search 
string, 7 3-16 
GOLD, 7 3-12 
HELP-KEYPAD, 7 3-13 
HELP-SPECIFICATIONS, 7 3-14 
LEFT, 7 3-28 
LINE, 7 3-27 

MOVE-TO-RULER, 7 3-20 
NEW-LINE, 7 3-28 
OPEN-LINE, 7 3-27 
PAGE, 7 3-18 

paging through the source file, 7 3-18 
PASTE, 7 3-21 

REFRESH-SCREEN, 7 3-29 
RESET, 7 3-27 
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Functions, (Cont.) 

REVIEW_ERROR, 7 3-19 
RIGHT, 73-28 
SECTION, 7 3-19 
SELECT, 7 3-27 

selecting alternate functions, 7 3-12 
SHIFTJLEFT, 7 3-22 
table, 7 3-10 
TOP, 7 3-21 

UNDELETE _FIELD, 7 3-20 
UNDELETE_LINE, 7 3-17 
UP, 7 3-27 


G 

GIVNG operation code, 77 3-26 
retrieving RTL return status, 77 3-26 
rules, 77 3-26 
GOLD function, 7 3-12 
GOTO operation code, 77 3-20 
example, 77 3-22 
rules, 77 3-21 


H 

Half adjust, 77 2-88 
rules for specifying, 77 2-88 
using resulting indicators, 77 3-26 
Halt indicators, 7 4-17 
controlling program execution, 7 4-17 
example, 7 4—17 to 4—18 
function, 7 4—17 
handling errors, 7 4-17 
Help window, 7 3-5 
definition, 7 3-6 

displaying help information, 7 3-6 
HELP_KE YPAD function, 7 3-13 
displaying help information on 
key functions, 7 3-14 
example, 7 3-14 

HELP_SPECIFICATIONS function, 7 3-14 
displaying specification formats 
example, 73-15 
HELP_SPECS function 
example, 7 3-54 

Hexadecimal character set, 77 A-l 


I/O areas 
specifying 

additional areas, 77 2-28 
IDENT field 
values, 7 2-10 
*IN indicators, 7 4—19 
example, 7 4-19 


*IN indicators, (Cont.) 
function, 7 4-19 
specifying arrays, 7 4-19 
*IN,n indicators, 7 4-19 
example, 7 4-19 
function, 7 4-19 

specifying array elements, 7 4-19 
Indexed file organization, 7 5^ 
example, 7 5-4 
index key, 7 5-4 
example, 7 5-4 
Indexed files 
adding records, 7 5-25 
example, 7 5-26 
rules for specifying, 7 5-25 
creating, 75-21 
example, 7 5-22 
rules for specifying 7 5-21 
specifying 

addition of records, 77 2-32 
Key length, 77 2-27 
Key location, 77 2-29 
updating records 
rules for specifying, 7 5-27 
Indicators, 7 4-1 

Calculation specification, 77 2-82 
example, 77 2-83 
conditioning 

calculations, 77 2-82 
output, 77 2-100 

control-level, 7 4-8,77 2-71, 2-80 
external, 7 4-16 
field, 7 4-4,77 2-78 
field-record-relation, 77 2-75 
first-page, 7 4-14, 6-8 
function, 7 4-1 
halt, 7 4-17 to 4-18 
*IN, 7 4-19 
*IN,n, 7 4—19 
internally defined, 7 4-14 
*INxx, 74-19 
last-record, 7 4-15 
matching-record, 7 4-16 
negating, 77 2-82 
Output specification 
example, 77 2-102 
rules for specifying, 77 2-100 
overflow, 7 4-12, 6-10,77 2-29 
IP, 7 4-14, 6-8 
printer output files, 7 6-8 
record-identifying, 7 4-1,77 2-56 
resulting, 7 4-6,77 2-88 
setting off, 77 3-9 
setting on, 77 3-9 
usage, 7 4-1 
user-defined, 7 4-1 
using as fields, 7 4-19 
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Input files 

selecting Mode of processing, II 2-24 
specifying 

File addition, II 2-32 
Unordered output, II 2-32 
Input specification, II 2-50 
AND, 7/2-61 
Character, II 2-60 
Control-level indicators, II 2-71 
copy from CDD, II 2-7 
copy modifiers, II 2-9 
CZD portion, II 2-59 
Data format, II 2-62 
Data structure, II 2-50 
Data structures, II 2-52 
data structures 

examples, II 2-66 to 2-68 
Decimal positions, II 2-64 
Field indicators, II 2-78 
Field locations, II 2-63 
Field name, II 2-64 

Field-record-relation indicators, II 2—75 
File name, 77 2-51 
format, 77 2-51 

identifying record types, 77 2-56 

Matching fields, 77 2-73 

Not, 77 2-59 

Number, 77 2-56 

Optional, 77 2-56 

OR, 77 2-61 

Position, 77 2-59 

Record identification codes, 77 2-58 
Record-identifying indicators, 77 2-56 
Sequence, 77 2-55 
specifying 

alphabetic sequence code, 77 2-55 
data formats, 77 2-62 
data structure statement, 77 2-53 
data structure subfield, 77 2-53 
file names 
example, 77 2-52 
input file names, 77 2-51 
look-ahead fields, 77 2-57 
numeric sequence code, 77 2-55 
record identification codes, 77 2-58 
sequence code, 77 2-55 
update file names, 77 2-51 
Type, 77 2-51 

Input/output operation codes, 77 3-14 
CHAIN, 77 3-14 
DSPLY, 77 3-16 
EXCPT, 773-17 
FORCE, 77 3-18 
READ, 77 3-19 
SETLL, 77 3-19 
Inverted print, 77 2-12 
*INxx indicators, 7 4-19 
example, 7 4-20 


*INxx indicators, (Cont.) 
function, 7 4—19 
representing indicators, 7 4—19 


JOURNAL qualifier, 7 3-3 


K 

K indicators, 7 4-12 
example, 7 4-12 
Key length 

ADDROUT files, 77 2-27 
example, 77 2-27 
Indexed files, 77 2-27 
Record-limits files, 77 2-27 
rules for specifying, 77 2-27 
Key location, 77 2-29 
rules for specifying, 77 2-29 
Keypad, 7 3-9 


Label names, 77 1-7 
Language elements, 77 1-1 
Last-record indicators, 7 4-15 
example, 7 4-15 
function, 7 4-15 
totalling data, 7 4-15 
LEFT function, 7 3-28 
Length of entry, 77 2^3 
arrays, 77 2-43 
rules for specifying, 77 2-43 
tables, 77 2-43 

Line Counter specification, 77 2-47 
example, 77 2-50 
File name, 77 2-48 
FL, 77 2-49 
Form length, 77 2^19 
format, 77 2-48 

naming the output file, 77 2-48 
OL, 77 2-50 

Overflow line number, 77 2—49 
Type, 77 2-48 
LINE function, 7 3-27 
example,/ 3-73 
Line numbers, 77 2-4 
checking, 7 2-8,77 2-4 
Line relationships 
AND, 77 2-61 
OR, 77 2-61 
LINK command, 7 2-8 
example, 7 2-9 
format, 7 2-9 
Linking programs, 7 2-8 
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LIST qualifier, 72-6 
format, 72-6 

generating a listing file, 72-6,11-1 
including cross-reference 
information, 72-6 
including machine code, 72-6 
Listing file 
generating, 72-6 
Local data area, II 2-55 
examples, II 2-69 
Logic cycle, 1 1-1 
detail time, 1 1-2,1-5 
flowchart, 1 1-6 
general, 1 1—2 

look-ahead processing, 1 1-20 
matching-fields routine, 1 1-16 
normal cycle, 1 1-3 
overflow processing, 1 1-19 
processing chained and demand files, 

1 1-18 
steps of 

a normal cycle, 7 1-3 
the first cycle, 71-2 
the last cycle, 1 1-3 
the first cycle, 1 1-2 
the last cycle, 1 1-3 
total time, 1 1-2,1-4 
LOKUP operation code, II 3-22 
arrays,/ 8-15 
example, 1 8-16 
example, II 3-24 to 3-25 
referencing entries, 1 7-10 
searching 

arrays, II 3-24 
related tables, II 3-23 
tables, 7 7-7,7/3-23 
specifying array elements, 77 3-24 
Long character literals, 77 2-111 
Longword binary data type example, 771-3 
Look-ahead fields, 77 2-57 
example, 77 2-57 
function, 77 2-57 
logic cycle, 71-20 
flowchart, 71-20 
rules for specifying, 77 2-58 
LR indicators, 7 4-15 


M 

MACHINE_CODE qualifier, 7 2-7 
format, 7 2-7 

generating machine code, 7 2-7,11-1 
Magnetic tape device 
specifying, 77 2-30 
Magnetic tapes 
rewinding, 77 2-37 


Matching fields, 77 2-73 
checking record sequence, 7 5-29,77 2-20 
example, 7 5-30 

for more than one record type, 7 5-29 
example, 7 5-30 
logic cycle, 7 1-16 
flowchart, 7 1-16 
multifile processing, 7 5-29, 5-33 
example, 7 5-34, 5-38 
record selection, 7 5-33 
rules for specifying, 7 5-34 
rules for specifying, 77 2-73 
using as field-record-relation indicators, 
75-31 

example, 7 5-31 to 5-33 
Matching-record indicators, 7 4-16 
function, 7 4-16 
multifile processing, 7 4-16 
Message line, 7 3-5 
definition, 7 3-7 
example, 7 3-7 
Mode of processing, 77 2-23 
example, 77 2-26 
loading a direct file, 77 2-23 
rules for specifying, 77 2-23 
selecting, 77 2-24 
specifying 
access 

random, 77 2-23 
sequential, 77 2-23 
sequential within limits, 77 2-23 
an ADDROUT file, 77 2-23 
Record address type, 77 2-28 
Modular Programming Standard, 7 9-32 
MOVE operation code, 77 3-5 
example, 77 3-7 
rules, 77 3-5 

Move operation codes, 77 3-5 
example, 77 3-7 
MOVE, 77 3-5 
MOVE A, 77 3-6 
MOVEL, 77 3-6 

MOVE_TO_RULER function, 7 3-20 
MOVE A operation code, 77 3-6 
arrays, 7 8-18 
example, 7 8-19,77 3-7 
rules, 77 3-6 

MOVEL operation code, 77 3-6 
example, 77 3-7 
rules, 77 3-6 

MULT operation code, 77 3-3 
example, 77 3-4 
Multifile processing, 7 5-29 
checking record sequence, 7 5-29 
example, 7 5-30 

for more than one record types, 7 5-29 
matching fields, 7 5-30 


12 Master Index 



Multifile processing, (CONT.) 
using 

matching fields, 75-29 
matching-record indicators, 74—16, 5-29 
MR indicators, 75-29 
multiple keys, 75^41 
Multiplication operation, II 3-3 
MVR operation code, II 3-3 
example, II 3^4 
saving the remainder, II 3-3 


Names 
arrays, II 1-7 
specifying, II 2-41 
EXCPT, 7/1-7 
fields, 7/1-6 
files, 771-6 
labels, 771-7 
PLIST, 771-7 
subroutines, 77 1-7 
tables, 771-7 
specifying, 77 2-41 
user-defined, 77 1-6 
NEW_LINE function, 7 3-28 
Not 

see record identification codes 
Notations 
Edit codes, 77 2-12 
numeric fields, 77 2-12 
UDATE, 7/2-12 
Number, 77 2-56 
rules for specifying, 77 2-56 
Number of entries per record, 77 2-42 
arrays, 77 2^42 
rules for specifying, 77 2-42 
tables, 77 2-42 

Number of entries per table or array, 77 2^42 
rules for specifying, 77 2-43 
Numeric data 
specifying 
format, 77 2-109 
Numeric fields 
editing, 77 2-112 
example, 77 2^4 
rounding, 77 2-88 
specifying 

notation, 77 2-12 
Numeric sequence code, 77 2-56 


0 

OBJECT qualifier, 7 2-7 
format, 7 2-7 

generating an object module, 7 2-7 


OBJECT qualifier, (Cont.) rules, 7 2-7 
specifying an output file, 7 2-7 
OL, 77 2-50 

OPEN_LINE function, 7 3-27 
Operation codes, 77 3-1 
arithmetic, 77 3-1 
ADD, 77 3-2 
DIV, 77 3-3 
MULT, 77 3-3 
MVR, 77 3-3 
SQRT, 77 3-4 
SUB, 77 3-3 
XFOOT, 77 3^4 
Z-ADD, 77 3-2 
Z-SUB, 77 3-3 
bit, 77 3-11 
BITOF, 77 3-12 
BITON, 77 3-11 
TESTB, 77 3-12 
branching, 77 3-20 
example, 77 3-22 
GOTO, 77 3-20 
TAG, 77 3-21 
compare, 77 3-13 
COMP, 77 3-13 
input/output, 77 3-14 
CHAIN, 77 3-14 
DSPLY, 77 3-16 
EXCPT, 77 2-103, 3-17 
FORCE, 77 3-18 
READ, 77 3-19 
SETLL, 77 3-19 
LOKUP, 77 3-22 
move, 77 3-5 
MOVE, 77 3-5 
MOVEA, 77 3-6 
MOVEL, 77 3-6 
set, 77 3-9 
SETOF, 77 3-9 
SETON, 77 3-9 
specifying, 77 2-86 
subprogram, 77 3-25 
CALL, 77 3-25 
EXTRN, 77 3-26 
GIVNG, 77 3-26 
PARM, 77 3-27 
PARMD, 77 3-28 
PARMV, 77 3-28 
PLIST, 77 3-29 
subroutine, 77 3-10 
BEGSR, 77 3-10 
ENDSR, 77 3-10 
EXSR, 77 3-10 
summary 
table, 77 3-31 
Optimizing 

file performance, 77 2-31 
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Optimizing programs, 712-1 
Expansion factor, 712-3 
file applications, 712-3 
file performance, 712-3 
file sharing, 712-3 
I/O processing, 712-3 
multiblock count, 712-3 
multibuffer count, 712-3 
with adjacent fields, 712-2 
with blank Factor 1,712-3 
with data structures, 712-1 
Optional, 772-56 
rules for specifying, II 2-56 
OR, 77 2-61, 2-91 
example, 77 2-62 
Output specification 
example, 77 2-92 
rules for specifying, 77 2-61, 2-91 
Output files 

controlling overflow, 77 2-29 
specifying 

File addition, 77 2-32 
File name, 77 2-48 
Unordered Output, 77 2-32 
using overflow indicators, 77 2-29 
OUTPUT qualifier, 7 3-3 
Output specification, 77 2-90 
AND, 77 2-91 
Blank after, 772-106 
Constants 

long character literals, 77 2-111 
copy from CDD, 77 2-7 
Data format, 77 2-109 
Edit code modifiers, 77 2-110 
Edit codes, 77 2-104 
Edit words, 77 2-112 
End position, 77 2-107 
Fetch overflow, 77 2-96 
Field name, 77 2-102 
File name, 77 2-91 
format, 77 2-90 
function, 77 2-90 
Indicators, 77 2-100 
OR, 77 2-91 
Record type, 77 2-93 
Skip after, 77 2-98 
Skip before, 77 2-98 
Space after, 77 2-97 
Space before, 77 2-97 
specifying 
ADD option, 77 2-95 
DEL option, 77 2-95 
Type, 77 2-90 
Overflow 
automatic, 7 6-13 

Overflow indicators, 7 4-12, 6-10,77 2-29 
causing page breaks, 7 4-12 
example, 7 4—12, 6—12 


Overflow indicators, (Cont.) 
function, 7 4-12 

rules for specifying, 7 6-10,77 2-29 
specifying, 7 4-12 
Fetch overflow, 77 2-96 
Overflow line number, 77 2-49 
OL, 77 2-50 

rules for specifying, 77 2-49 
Overflow processing 
logic cycle, 71-19 
flowchart, 7 1-19 
Overpunched decimal 
specifying, 77 2-44 
Overpunched decimal data type 
example, 771-6 

representation of least significant digit and 
sign, 771-5 

representation of nonleast 
significant digits, 77 1-5 
trailing numeric string, 77 1—4 


P 

IP indicators, 7 4-14, 6-8 
conditioning output data, 7 4-14 
example, 7 4-14, 6-9 
function, 7 4-14 
specifying, 7 4-14 
Packed decimal data type 
example, 771-4 
specifying, 77 2^14 
PAGE function, 7 3-18 
example, 7 3-18 
Page size 
defining, 7 6-14 
PAGE special word, 7 6-4 
changing the page number, 7 6-5 
example, 7 6—5 to 6—6 
resetting the page number, 7 6-6 
PAGE1 special word, 7 6-4 
PAGE2 special word, 7 6^1 
PAGE3 special word, 7 6-4 
PAGE4 special word, 7 6-4 
PAGE5 special word, 7 6-4 
PAGE6 special word, 7 6-4 
PAGE7 special word, 7 6-4 
Paging special words 
rules for specifying, 7 6-4 
Parameters 
list, 77 3-29 
passing 

access types, 77 3-27 
data types, 77 3-28 
mechanisms, 77 3-27 
by descriptor, 77 3-28 
by reference, 77 3-27 
by value, 77 3-28 
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PARM operation code, II 3-27 
example, 1 9-6, 9-11 
rules, II 3-27 

PARMD operation code, II 3-28 
example, 1 9-11, II 3-30 
rules, II 3-28 

PARMV operation code, II 3-28 
example, 1 9-10, 9-16 
rules, II 3-29 

Passing mechanisms, 1 9-18 
Paste buffer, 1 3-9 
PASTE function, 1 3-21 
example, 1 3-74 
PDP-11 RPGII 

comparison with VAX RPG II, II B-l 
See VAX RPG II, II B-l 
*PLACE special word, 1 6-7 
example, / 6-8 
rules for specifying, 1 6-7 
PLIST 

names, II 1-7 
operation code, II 3-29 
rules, II 3-29 
Position 

see record identification codes 
rules for specifying, II 2-59 
Pre-execution-time arrays, 1 8-4 
creating, 1 8-4, 8-6 
rules for specifying, 1 8-4 
outputting, I 8-20 
searching 
example,/ 8-17 
updating, 1 8-19 
writing, 1 8-20 

Pre-execution-time tables, 1 7-2 
creating 
example, 1 7-7 
outputting, 1 7-12 
rules for defining, 1 7-7 
updating, / 7-11 
example, 1 7-11 
writing, 1 7-12 
Primary files 

selecting Mode of processing, II 2-24 
Printer device 

specifying, II 2-30 
Printer output files, 1 6-1 
automatic overflow, 1 6-13 
changing page numbers, / 6-4 
checking the alignment, II 2-15 
conditioning output, / 6-8 
constants 
example, 1 6-2 
controlling overflow, II 2-29 
creating, / 6-1 
defining 

page numbers, 1 6—4 


Printer output files, defining (Cont.) 
page size, 1 6-14 
rules for specifying, / 6-14 
deleting form-feed characters, 1 6-1 
editing 

numeric data, II 2-112 
editing output, / 6-1, II 2-104 
first-page indicators, 1 4-14 
formatting, II 2-97 to 2-98 
output, 1 6-14 

output data, II 2-107, 2-110 
generating report titles, II 2-111 
last-record indicators, 1 4-15 
NOFEED qualifier, 1 6-1 
overflow indicators 
using, 1 4-12 
IP indicators, / 4—14 
paging, 1 6-4 
printing 

IMPORTANT INFORMATION, 1 6-1 
printing the date, 1 6-3 
repeating output records, 1 6-7 
resetting page numbers, 1 6^1 
Skip entries, 1 6-14 
example, 1 6-16 
Space entries, 1 6-14 
example, 1 6—16 
specifying 

a negative sign, II 2-116 
asterisks, II 2-113 
blank spaces, II 2-114 
commas, 7/2-115 
constant data, II 2-111 
CR,//2-116 

currency symbol, II 2-114 
decimal points, II 2-115 
Fetch overflow, II 2-96 
Overflow line number, II 2—49 
page breaks, 1 6-10 
page numbers, 1 6-4 
page size, II 2-49 
Skip after, II 2-98 
Skip before, II 2-98 
Space after, II 2-97 
Space before, II 2-97 
zero suppression, II 2-113 
using 

constants, 1 6-2 
Edit code modifiers, 1 6-2 
asterisk fill, 1 6-2 
floating dollar sign, 1 6-2 
Edit codes, / 6-1 
first-page indicators, / 6-8 
indicators to condition output, II 2-100 
overflow indicators, 1 6-10, II 2-29 
example, 1 6-12 
IP indicators, / 6-8 
special words, 1 6-3 
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Procedure Calling and Condition 
Handling Standard, 79-32 
Procedure calls, 79-19 
Processing 
branching, 773-20 
files 
chained 

flowchart, 1 1-18 
demand 

flowchart, 1 1-18 
specifying 

an ADDROUT file, II 2-23 
random access, II 2-23 
sequential access, II 2—23 
sequential within limits access, II 2-23 
look-ahead fields 
flowchart, 1 1-20 
multifiles, 1 5-29 
processing files 

multiple keys, 1 5-41 
example, 1 5-41 
Program development, 1 2-1 
compiling, 1 2-1 
linking, / 2-8 
running, 1 2-9 
Programs 

see RPGII programs 
branching, II 3-21 
developing, 1 2-1 
logic cycle, 1 1-1 
Prompt line, 1 3-5 
definition, 1 3-7 


Q 

Qualifiers 
see specific entries 
debugger, 1 10—1 
RPG command, 1 2-3 
RPG/EDIT command, 1 3-2 


R 

Random by ADDROUT file access, 1 5-14 
example, 7 5-17 
rules for specifying, 1 5-16 
Random by key file access, 1 5-13 
example, 1 5-14 
rules for specifying, 1 5-13 
Random file access, 1 5-11 
using 

an ADDROUT file, 1 5-14 
keys, 7 5-13 

relative record numbers, 7 5-11 
example, 7 5-12 
rules for specifying, 7 5-11 


READ operation code, 77 3-19 
demand files, 77 3-19 
example, 77 3-19 
full-procedural files, 77 3-19 
rules, 77 3-19 

RE AD_ONLY qualifier, 7 3-3 
Record address type, 77 2-28 
Record formats 
fixed, 7 5-2 
variable, 7 5-2 

Record identification codes, 77 2-58 
identifying record types, 77 2-58 
specifying 
Character, 77 2-60 
CZD portion, 77 2-59 
example, 77 2-60 
Not, 77 2-59 
Position, 77 2-59 
Record length, 77 2-22 
rules for specifying, 77 2-21 to 2-22 
Record types, 77 2-93 
defining the ordering sequence, 77 2-55 
detail, 77 2-93 
example, 77 2-94 
exception, 77 2-93 
heading, 77 2-93 
identifying, 77 2-56 
rules for specifying, 77 2-93 
specifying 

record identification codes, 77 2-58 
total, 77 2-93 
using record-identifying 
indicators, 7 4—2 
Record-address files 
selecting Mode of processing, 77 2-25 
specifying 

From file name, 77 2-40 
To file name, 77 2-40 
Record-identifying indicators, 77 2-56 
conditioning input data, 77 2-56 
example, 7 4—1, 4-3 
function, 7 4-1 

identifying record types, 7 4-1 
Record-limits files 
example, 7 5-8 
function, 7 5-8 
rules for specifying, 7 5-8 
specifying 
Key length, 77 2-27 
Records 

adding, 7 5-22,77 2-95 
array input/, 7 8^4 
changing processing order, 77 3-19 
deleting, 7 5-28,77 2-95 
example, 7 5-28 
general processing cycle, 7 1-2 
identifying types, 77 2-56 
processing totals, 7 1-4 
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Records (Cont.) 

record-identifying indicators, 74-1 
selecting 

SETLL operation code, 773-19 
specifying 
detail, 7/2-93 
exception, II 2-93 
format, II 2-21 
heading, II 2-93 
length 

fixed, II 2-21 
variable, II 2-21 

record identification codes, II 2-58 
total, II 2-93 
types, II 2-93 

defining the ordering sequence, II 2-55 
updating, 1 5-26 
example, 1 5-27 

using record-identifying indicators, 1 4-1 
writing during calculations, II 3—17 
RECOVER qualifier, 1 3-4 
REFRESH_SCREEN, 1 3-29 
Related arrays, 1 8-5 
alternate format, 1 8-8 
creating, 1 8-5, 8-8 
Related tables 
alternate format 
example, 7 7-11 
creating, 1 7-5 
example, 1 7-6 
input records, 1 7-3 
entries 

example, 11-k 
LOKUP operation code 
rules, II 3-23 
updating, 1 7-11 
RESET function, 1 3-27 
Result field, II 2-86 
rounding data, II 2-88 
rules for specifying, II 2-86 
Resulting indicators, 1 4—6, II 2-88 
arrays, 1 8-16 
example, 1 4-7 
function, 1 4-6 
rules for specifying, II 2—89 
specifying 

result of search, II 3-23 
type of search, II 3-22 
testing calculation results, 1 4-6 
types of tests, 7 4-6 
using Half adjust, II 3-26 
RETURN key 
example, 1 3-55 

REVIEW_ERROR function, 1 3-19 
RIGHT function, 73-28 
example, 1 3-54 


RPG command 
defining as a symbol, 1 2-2 
format, 1 2-1 
qualifiers, 1 2-3 
CHECK, 1 2-4 

CROSS_REFERENCE, 1 2-5 
DEBUG, 7 2-6 
example, 7 2-3 to 2-4 
format, 7 2-3 
LIST, 7 2-6 

MACHINE_CODE, 7 2-7 
negating, 7 2-3 
OBJECT, 7 2-7 
SEQUENCE_CHECK, 7 2-8 
table, 7 2-k 
WARNINGS, 7 2-8 
RPG II editor, 7 3-1 

auto right justification of numeric fields, 

7 3-44 

blinking the current column, 7 3—26 
buffers, 7 3-9 
current, 7 3-9 
deleted-field, 7 3-9 
deleted-line, 7 3-9 
paste, 7 3-9 

compiling programs, 7 3-30 
creating 

a new program line, 7 3-27 to 3-28 
programs 
example, 7 3-54 
creating files, 7 3-3 
cursor, 7 3-8 
customizing, 7 3-48 
editor commands, 7 3—48 
example, 7 3-48 
startup command file, 7 3-48 
SET COMMAND option, 7 3-48 
deleting 

a character and shifting the program line 
left, 7 3-22 

a character and shifting the program line 
right, 7 3-22 

characters from the cursor to the end of 
the line, 7 3-25 
fields, 7 3-20 

determining where the editor starts, 7 3^1 
displaying 

current column setting, 7 3-46 
current DEFAULT setting, 7 3-46 
current SCROLL setting, 7 3-46 
current SECTION setting, 7 3-46 
current SYNTAXCHECK setting, 7 3-46 
help information, 7 3-35 
program, 7 3-19 

version number and copyright, 7 3-46 
editing an existing program 
example, 7 3-66 
finding the next error, 7 3-19 
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RPGII editor, (Cont.) 
functions 

displaying help information, 73-13 
inserting the contents of the 
paste buffer, 73-21 
invoking, 73-1 
example, 73-54 
keypad, 73-9 
displaying 

keypad diagram, 73-13 
example, 73-9 
naming conventions, 73-10 
leaving the editor, 73-34, 3-38 
moving 

current line, 73-27 
current line to the ruler, 73-20 
sections of the editing buffer, 73-19 
moving cursor 
backward, 7 3-21 
down, 7 3-28 
left, 7 3-28 
right, 7 3—28 

to end of a program line, 7 3-24 
to first line, 73-21 
to last line, 7 3-21 
to next character, 7 3-26 
to next field, 7 3-23 
to next tab stop, 7 3-29 
to preceding tab stop, 7 3-28 
up, 73-27 

naming the output file, 7 3-3 to 3-4 
numbering program lines, 7 3-39 
overstriking, 7 3-1 

placing selected text into the paste buffer, 
7 3-21 

recovering edits, 7 3-4 
renumbering existing program lines, 

7 3-39 
replacing 

the preceding character with a space, 
73-28 

the program line with spaces, 7 3-29 
resetting the select range, 7 3-27 
rewriting the screen display, 7 3-29 
saving edits, 7 3-3 
screen, 7 3-5 

selecting a range of lines for the paste 
buffer, 7 3-27 
setting 

terminal characters, 7 3-9 
the current direction forward, 7 3-20 
the location of the ruler, 7 3-41 
the number of display lines, 7 3-44 
the scroll region, 7 3-43 
single line syntax check, 7 3—44 
specifying the current column, 7 3-44 
startup command, 7 3-2 


RPG II editor, (Cont.) 
terminating RPG II editor command 
entries, 7 3-26 
undeleting fields, 7 3-20 
viewing programs, 7 3-3 
VK100 (GIGI) terminal, 7 3-5 
writing the editing buffer to an output file, 
7 3-29 

RPG II editor commands 
COMPILE, 7 3-30 
DEFINE KEY, 7 3-31 
EXIT, 7 3-34 
example, 7 3-34 
SAVE qualifier, 7 3-35 
HELP, 7 3-35 
example, 7 3-35, 3-37 
INCLUDE, 7 3-37 
QUIT, 7 3-38 
example, 7 3-38 
SAVE qualifier, 7 3-39 
RESEQUENCE, 7 3-39 
options, 7 3-39 
REMOVE, 7 3-39 
SEQUENCE 
example, 7 3-39 
SET, 7 3-40 
format, 7 3-40 
options 

COMMAND, 7 3-40 
HELP KEYPAD, 7 3-41 
HELP NONE, 7 3-41 
HELP SPECIFICATIONS, 7 3-41 
RULER, 7 3-41 
SCROLL, 7 3-43 
SECTION, 7 3-44 
STARTCOLUMN, 7 3-44 
SYNTAXCHECK, 7 3-44 
SHOW, 7 3-45 
options 

DEFAULT, 7 3-46 
SCROLL, 7 3-46 
SECTION, 7 3-46 
STARTCOLUMN, 7 3-46 
SYNTAXCHECK, 7 3-46 
VERSION, 7 3-46 
SUBSTITUTE, 7 3^6 
RPG II editor EXIT command 
example, 7 3-76 

RPG II editor RESEQUENCE command 
example, 7 3-71, 3-75 
RPG II editor screen 
80-column ruler, 7 3-5 
definition, 7 3-7 
example, 7 3-6 to 3-7 
displaying help information, 7 3-6 
editing window, 7 3-5 
example, 7 3-7 
EOB mark, 7 3-7 
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RPGII editor screen (Cont.) 
help window, 73-5 
displaying help information, 73-6 
example, 73-6 
message line, 7 3-5 
definition, 73-7 
example, 7 3-6 to 3-8 
prompt line, 73-5 
definition, 73-7 
example, 7 3-6, 3-8 
source window 
example, 73-6 
specification format 
example, 7 3—8 
tab stops, 73-5 
definition, 73-7 
example, 73-6 to 3-7 
RPG II editor SECTION function 
example, 7 3-72 

RPG II editor SHOW command, 73-45 
RPG II editor SHOW STARTCOLUMN 
command 
example, 7 3-55 
RPG II programs 
arrays, 78-1 
call interface, 79-1 
calling 

subprograms, 79-32 
system services, 79-28 
compiling, 72-1 
creating, 7 3-1 
debugging, 710-1 
developing, 72-1 
documenting, II2-5 
editing, 1 3-1 
linking, 1 2-8 
logic cycle, 71-1 
optimizing, 1 12-1 
running, 1 2—9 
viewing, 1 3-1 
RPG II specifications, II 2-1 
RPG/DEBUG, 710-1 
RPG/EDIT command, 7 3-1 
qualifiers 
COMMAND, 7 3-2 
CREATE, 7 3-3 
JOURNAL, 7 3-3 
OUTPUT, 7 3-3 
RE AD_ONLY, 7 3-3 
RECOVER, 7 3-4 
START_POSITION, 7 3-4 
table, 7 3-2 

RTL parameter access types 
modify, 7 9-12 
read only, 7 9-12 
write only, 7 9-12 
example, 7 9-12 


RTL parameter data types 

double precision floating point, 7 9-12 
longword integer, 7 9-12 
numeric string, 7 9-12 
example, 7 9-13 
packed decimal string, 7 9-12 
quadword integer, 7 9-12 
single precision floating point, 7 9-12 
text string, 7 9-12 
word integer, 7 9-12 
RTL parameter passing mechanisms 
by descriptor 
example, 79-11 
by reference 
example, 7 9-6, 9-11 
by value, 7 9-10, 9-16 
example, 7 9-10, 9-16 
RTL procedures 
assigning names, 77 3-26 
calling, 77 3-25 

example, 7 9-14, 9-16 to 9-18, 9-24 to 
9-27 

GIVNG operation code, 77 3-26 
parameter characteristics 
access types, 7 9-12 
data types, 7 9-12 
passing mechanisms, 7 9-10, 9-18 
parameter passing mechanisms 
by descriptor, 7 9-10 
PARMD operation code, 7 9-10 
by reference, 7 9-10 
PARM operation code, 7 9-10 
by value, 7 9-10 
example, 7 9-10, 9-16 
PARMV operation code, 7 9-10 
passing parameters, 77 3-27 to 3-28 
RTL routines 
Arguments 
optional, 7 9-5 
required, 7 9-5 
Ruler, 7 3-5 
RUN command, 7 2-9 
example, 7 2-9 
format, 7 2-9 

Run-Time Library routines, 7 9-2 
example of calling, 7 9-24 
facilities, 7 9-2 
how to call, 7 9-3 
Running programs, 7 2-9 


S 

Screen handling, 7 9-33 
FMS, 7 9-33 to 9-34 
example, 7 9-34 
SMG, 7 9-33, 9-35 
example, 7 9-35 
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Screen handling, (Cont.) 

TDMS, 79-33 
example, 79-33 to 9-34 
Secondary files 

selecting Mode of processing, II 2-24 
SECTION function, 1 3-19 
SELECT function, 1 3-27 
example, 1 3-74 

Sequence codes, II 2-20, 2^15, 2-55 
assigning a numeric code, II 2-56 
Number, II 2-56 

rules for specifying, II 2-20, 2-Ab 
specifying 
alphabetic, II 2-55 
continued processing, II 2-56 
numeric, II 2-55 to 2-56 
SEQUENCE.CHECK qualifier, 1 2-8 
checking line number sequence, 1 2-8 
format, 1 2-8 

Sequential by key file access 
example, 1 5-7 
rules for specifying, 7 5-7 
Sequential file access, 1 5-6 
example, 1 5-6 
rules for specifying, 1 5-6 
Sequential file organization, 1 5—2 
example, 1 5-3 
Sequential files 
adding records, 1 5-23 
example, 1 5-23 
rules for specifying, 1 5-23 
creating, 1 5-20 
example, 7 5-20 
rules for specifying, 1 5-20 
Sequential within limits file access 
example, 1 5-10 
record-limits file, 7 5-8 
SET COMMAND option, 1 3-48 
Set operation codes, II 3-9 
example, II 3-9 
SETON, 7/3-9 

SETLL operation code, II 3-19 
example, II 3-20 
rules, 773-19 

selecting the next record, 77 3-19 
SETOF operation code, 77 3-9 
example, 77 3-9 
rules, 77 3-9 

SETON operation code, 77 3-9 
example, 77 3-9 
rules, 77 3-9 

SHIFT_LEFT function, 7 3-22 
example, 7 3-22 

SHIFT_RIGHT function, 7 3-22 
example, 7 3-23 
Skip after, 77 2-98 
example, 77 2-99 
rules for specifying, 77 2-99 


Skip before, 77 2-98 
example, 77 2-99 
rules for specifying, 77 2-99 
SMG, 7 9-33, 9-35 
Space after, 77 2-97 
rules for specifying, 77 2-97 
Space before, 77 2-97 
rules for specifying, 77 2-97 
Special words, 7 6-3 
PAGE, 7 6-4 
PAGE1J6-4 
PAGE2,7 6-4 
PAGE3,/6^1 
PAGE4,7 6-4 
PAGE5,7 6-4 
PAGE6,7 6-4 
PAGE7,/6-4 
paging, 7 6-4 
*PLACE, 7 6-7 
rules for specifying, 7 6—4 
UDATE,/ 6-3 
UDAY 

example, 7 6-4 
UMONTH 
example, 7 6-4 
UYEAR 
example, 7 6-4 
Specification format 
asterisks, 77 2-3 
column numbers, 77 2-2 
comments, 77 2-5 
dashes, 77 2-3 
dots, 77 2-3 
line number, 77 2-4 
notational conventions, 77 2-2 
Specifications 
Calculation, 77 2-79 
Control, 77 2-11 
Extension, 77 2-38 
File Description, 77 2-16 
format, 77 2-2 
Input, 77 2-50 
Line Counter, 77 2-47 
Output, 77 2-90 
RPG 11,77 2-1 
types, 77 2-5 
Split-control fields 
example, 7 4-11 
SQRT operation code, 77 3^ 
example, 77 3-4 
Square root operation, 77 3-4 
START_POSITION qualifier, 7 3-4 
Startup command file, 7 3-48 
SUB operation code, 77 3-3 
example, 77 3-4 

Subprogram operation codes, 77 3-25 
CALL, 77 3-25 
EXTRN, 77 3-26 
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Subprogram operation codes, (Cont.) 
GIVNG, 7/3-26 
PARM, 7/3-27 
PARMD, 77 3-28 
PARMV, 77 3-28 
PLIST, 77 3-29 
Subprograms, 7 9-32 
calling, 77 3-25 
example, 7 9-32 
parameter list, 77 3-29 
passing parameters, 77 3-27 to 3-28 
PLIST, 77 3-29 
Subroutines 
executing, 77 3-10 
marking the beginning, 77 3-10 
marking the ending, 77 3-10 
names, 77 1-7 
operation codes, 77 3-10 
BEGSR, 77 3-10 
ENDSR, 77 3-10 
example, 77 3-10 
EXSR, 77 3-10 

Subtraction operation, 77 3-3 
Symbolic device, 77 2-31 
System routines, 7 9-1 
determining the type of call 
function, 7 9-4 
procedure, 7 9^1 
examples of calling, 7 9-24 
function calls, 7 9-15 
function results, 7 9-23 
how to call, 7 9-3 
passing mechanisms, 7 9-18 
procedure calls, 7 9-19 
procedure results, 7 9-23 
System services, 7 9-28 
calling, 77 3-25 
example, 7 9-29 to 9-31 
determining the type of call 
function, 7 9^1 
procedure, 7 9-4 
groups, 7 9-3 
how to call, 7 9-3 

passing parameters, 77 3-27 to 3-28 
routines, 7 9—2 
symbolic constants 
example, 7 9-22 


TAB function 
example, 7 3-54 
Tab stops, 7 3-5 
definition, 7 3-7 
Table or array name, 77 2-41 
rules for specifying, 77 2-41 


Tables, 7 7-1 
alternate format, 77 2^5 
compile-time, 7 7-2 
rules for defining, 7 7-6 
creating 

input records, 7 7-3 
definition, 7 7-1 
entries, 7 7-3 
input records, 7 7-3 
creating, 7 7-3 
example, 7 7-3 
rules for specifying, 7 7-3 
loading time 
selecting, 7 7-1 

LOKUP operation code, 7 7-7,77 3-23 
names, 77 1-7 
outputting 
example, 7 7-12 
rules for specifying, 7 7-12 
pre-execution-time, 7 7-2 
rules for defining, 7 7-7 
referencing entries, 7 7-10 
example, 7 7-10 
related, 7 7-1, 7-3 
creating, 7 7-5 
example, 7 7-6 
example, 7 7-11 
updating, 7 7-11 
searching, 7 7-7,77 3-23 
example, 77 3-24 
rules for specifying, 7 7-8 
single, 7 7-1 
creating, 7 7-4 
example, 7 7-5 
specifying, 77 2-18 
alternate format, 77 2-45 
current entry, 7 7-10 
example, 7 7-11 
Data format, 77 2-44 
Decimal positions, 77 2^4 
From file name, 77 2-40 
Length of entry, 77 2-43 
names, 77 2-41 

Number of entries per record, 77 2-42 
Number of entries per table or array, 
772-42 

sequence, 7 7-9,77 2-45 
ascending, 7 7-9 
descending, 7 7-9 
example, 7 7-9 
To file name, 77 2^10 
updating, 7 7-11 
writing, 7 7-12 
TAG operation code, 77 3-21 
example, 77 3-22 
rules, 773-21 
Tapes 

rewinding, 77 2-37 
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Tapes (Cont.) 
specifying 
labels, 7/2-31 
ANSI, 7/2-31 
TDMS, 7 9-33 
Terminal device 
specifying, 77 2-30 
TESTB operation code, 77 3-12 
example, 77 3-12 
rules, 77 3-12 
To file name 
outputting 
arrays, 77 2-40 
tables, 77 2-40 
record-address files, 77 2-40 
rules for specifying, 77 2-41 
writing 
arrays, 77 2-40 
tables, 77 2-40 
TOP function, 7 3-21 
Total time, 71-2,1-4 
Type, 77 2-90 


u 

UDATE special word, 7 6-3 
defining, 7 6-3 
editing, 7 6-3 

specifying notation, 77 2-12 
UNDELETE_FIELD function, 7 3-20 
UNDELETE_LINE function, 7 3-17 
Unordered output, 77 2-32 
rules for specifying, 77 2-33 
UP function, 7 3-27 
example, 73-73 
Update files 

selecting Mode of processing, 77 2-24 
specifying 

File addition, 77 2-33 
Unordered output, 77 2-33 
Updating 
files, 7 5-26 

randomly by key, 7 5-28 
sequentially, 7 5-28 
records, 7 5-26 
example, 7 5-27 
User-defined names, 77 1-6 
rules, 771-7 


V 

VAX Procedure Calling and 

Condition Handling Standard, 7 9-32 
VAX RPGII 

differences between PDP-11 RPG II, 77 B-l 
different support, 77 B-2 
editor 

nonsupported functionality, 77 B-7 
new functionality, 77 B-5 
nonsupported functionality, 77 B-l 
new functionality, 77 B-5 
VAX/VMS Modluar Programming Standard, 
7 9—32 

VMS Usages, 7 9-7 
VAX RPG II equivalents, 7 9-7 


W 

WARNINGS qualifier, 7 2-8 
displaying 

error messages, 7 2-8 
information messages, 7 2-8 
format, 7 2-8 
options, 7 2-8 
INFORMATION, 7 2-8 
OTHER, 7 2-8 
Word binary data type 
example, 77 1-3 


X 

XFOOT operation code, 77 3-4 
arrays, 7 8-14 
example, 7 8-15 

referencing array elements, 7 8-15 


Z-ADD operation code, 77 3-2 
example, 77 3^ 

Z-SUB operation code, 77 3-3 
example, 77 3-4 
Zero suppression, 77 2-113 
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Programming in 
VAX RPG II 
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READER'S 
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